about_Throw

Mis à jour: mai 2014

S'applique à: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

RUBRIQUE

about_Throw

DESCRIPTION COURTE

Décrit le mot clé Throw qui génère une erreur avec fin d'exécution.

DESCRIPTION DÉTAILLÉE

Le mot clé Throw entraîne une erreur avec fin d'exécution. Vous pouvez utiliser le mot clé Throw pour arrêter le traitement d'une commande, d'une fonction ou d'un script.

Par exemple, vous pouvez utiliser le mot clé Throw dans le bloc de script d'une instruction If pour répondre à une condition ou dans le bloc Catch d'une instruction Try-Catch-Finally. Vous pouvez également utiliser le mot clé Throw dans une déclaration de paramètre pour configurer un paramètre de fonction obligatoire.

Le mot clé Throw peut lever n'importe quel objet, tel qu'une chaîne de message utilisateur ou l'objet qui a provoqué l'erreur.

SYNTAXE

La syntaxe du mot clé Throw est la suivante :

        throw [<expression>]

L'expression de la syntaxe Throw est facultative. Si l'instruction Throw n'apparaît pas dans un bloc Catch et ne comprend pas d'expression, une erreur ScriptHalted est générée.

        C:\PS> throw

        ScriptHalted
        At line:1 char:6
        + throw <<<<
            + CategoryInfo          : OperationStopped: (:) [], RuntimeException
            + FullyQualifiedErrorId : ScriptHalted

Si le mot clé Throw est utilisé dans un bloc Catch sans expression, l'exception RuntimeException est de nouveau lancée. Pour plus d'informations, consultez about_Try_Catch_Finally.

LEVÉE D'UNE CHAÎNE

L'expression facultative d'une instruction Throw peut être une chaîne, comme indiqué dans l'exemple suivant :

        C:\PS> throw "This is an error."

        This is an error.
        At line:1 char:6
        + throw <<<<  "This is an error."
            + CategoryInfo          : OperationStopped: (This is an error.:String) [], RuntimeException
            + FullyQualifiedErrorId : This is an error.

LEVÉE D'AUTRES OBJETS

L'expression peut également être un objet qui lève l'objet qui représente le processus PowerShell, comme indiqué dans l'exemple suivant.

        C:\PS> throw (get-process PowerShell)

        System.Diagnostics.Process (PowerShell)
        At line:1 char:6
        + throw <<<<  (get-process PowerShell)
            + CategoryInfo          : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], 
        RuntimeException
            + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell)

Vous pouvez utiliser la propriété TargetObject de l'objet ErrorRecord dans la variable automatique $error pour examiner l'erreur.

        C:\PS> $error[0].targetobject

        Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName                                                            
        -------  ------    -----      ----- -----   ------     -- -----------                                                            
            319      26    61016      70864   568     3.28   5548 PowerShell

Vous pouvez aussi lever un objet ErrorRecord ou une exception Microsoft .NET Framework. L'exemple suivant utilise le mot clé Throw pour lever un objet System.FormatException.

        C:\PS> $formatError = new-object system.formatexception

        C:\PS> throw $formatError

        One of the identified items was in an invalid format.
        At line:1 char:6
        + throw <<<<  $formatError
            + CategoryInfo          : OperationStopped: (:) [], FormatException
            + FullyQualifiedErrorId : One of the identified items was in an invalid format.

ERREURS RÉSULTANTES

Le mot clé Throw peut générer un objet ErrorRecord. La propriété Exception de l'objet ErrorRecord contient un objet RuntimeException. Le reste de l'objet ErrorRecord et de l'objet RuntimeException varie selon l'objet levé par le mot clé Throw.

L'objet RunTimeException est encapsulé dans un objet ErrorRecord, et l'objet ErrorRecord est automatiquement enregistré dans la variable automatique $Error.

UTILISATION DU MOT CLÉ THROW POUR CRÉER UN PARAMÈTRE OBLIGATOIRE

Vous pouvez utiliser le mot clé Throw pour configurer un paramètre de fonction obligatoire.

Il s'agit d'une alternative à l'utilisation du paramètre Mandatory du mot clé Parameter. Quand vous utilisez le paramètre Mandatory, le système invite l'utilisateur à entrer la valeur du paramètre requis. Quand vous utilisez le mot clé Throw, la commande s'arrête et affiche l'enregistrement de l'erreur.

Par exemple, le mot clé Throw de la sous-expression de paramètre fait du paramètre Path un paramètre obligatoire de la fonction.

Dans ce cas, le mot clé Throw lève une chaîne de messages, mais c'est la présence du mot clé Throw qui génère l'erreur avec fin d'exécution si le paramètre Path n'est pas spécifié. L'expression qui suit le mot Throw est facultative.

        function Get-XMLFiles
        {
            param ($path = $(throw "The Path parameter is required."))
            dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name  -auto
        }

VOIR AUSSI

about_Break

about_Continue

about_Scope

about_Trap

about_Try_Catch_Finally