about_Throw

適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0

トピック

about_Throw

概要

終了するエラーを生成する Throw キーワードについて説明します。

詳細説明

Throw キーワードにより、終了するエラーが発生します。Throw キーワードを使用すると、コマンド、関数、またはスクリプトの処理を停止できます。

たとえば、条件に応答するために If ステートメントのスクリプト ブロックや、Try-Catch-Finally ステートメントの Catch ブロックで Throw キーワードを使用できます。また、パラメーターの宣言で Throw キーワードを使用して、関数パラメーターを必須にすることもできます。

Throw キーワードでは、ユーザー メッセージ文字列やエラーの原因になったオブジェクトなどの任意のオブジェクトをスローできます。

構文

Throw キーワードの構文は次のとおりです。

        throw [<expression>]

Throw 構文内の式はオプションです。Throw ステートメントが Catch ブロックに記述されず、Throw ステートメントに式が含まれていない場合は、ScriptHalted エラーが生成されます。

        C:\PS> throw

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

Throw キーワードが式なしで Catch ブロックで使用されている場合は、現在の RuntimeException がもう一度スローされます。詳細については、「about_Try_Catch_Finally」を参照してください。

文字列のスロー

Throw ステートメント内のオプションの式は、次の例に示すように、文字列にすることができます。

        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.

その他のオブジェクトのスロー

式も、次の例に示すように、PowerShell プロセスを表すオブジェクトをスローするオブジェクトにすることができます。ここにセクション本体を挿入します。

        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)

$error 自動変数に ErrorRecord オブジェクトの TargetObject プロパティを使用すると、エラーを確認できます。

        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

また、ErrorRecord オブジェクトまたは Microsoft .NET Framework 例外をスローすることもできます。次の例では、Throw キーワードを使用して、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.

生成されるエラー

Throw キーワードでは、ErrorRecord オブジェクトを生成できます。ErrorRecord オブジェクトの Exception プロパティには、RuntimeException オブジェクトが含まれています。ErrorRecord オブジェクトと RuntimeException オブジェクトの残りの部分は、Throw キーワードがスローするオブジェクトによって異なります。

RunTimeException オブジェクトは ErrorRecord オブジェクトにラップされ、ErrorRecord オブジェクトは自動的に $Error 自動変数に保存されます。

Throw を使用した必須パラメーターの作成

Throw キーワードを使用して、関数パラメーターを必須にすることができます。

これは、Parameter キーワードの Mandatory パラメーターを使用する代わりとなるものです。Mandatory パラメーターを使用すると、ユーザーは必須パラメーター値を入力するように求められます。Throw キーワードを使用すると、コマンドが停止し、エラー レコードが表示されます。

たとえば、パラメーターのサブ式で Throw キーワードを使用すると、Path パラメーターが関数の必須パラメーターになります。

この場合、Throw キーワードはメッセージ文字列をスローしますが、Path パラメーターが指定されていない場合に終了するエラーが生成されるのは Throw キーワードが存在しているためです。Throw に続く式はオプションです。

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

関連項目

about_Break

about_Continue

about_Scope

about_Trap

about_Try_Catch_Finally