終了するエラー

このトピックでは、終了エラーの報告に使用されるメソッドについて説明します。また、コマンドレット内からメソッドを呼び出す方法についても説明し、メソッドが呼び出されたときに Windows PowerShell ランタイムによって返される可能性がある例外についても説明します。

終了エラーが発生した場合、コマンドレットは、System.Management.Automation.Cmdlet.ThrowTerminatingError* メソッドを呼び出してエラーを報告する必要があります。このメソッドを使用すると、コマンドレットは、終了エラーの原因となった条件を説明するエラーレコードを送信できます。エラーレコードの詳細については、「Windows PowerShell エラーレコードの」を参照してください。

System.Management.Automation.Cmdlet.ThrowTerminatingError* メソッドが呼び出されると、Windows PowerShell ランタイムはパイプラインの実行を永続的に停止し、System.Management.Automation.PipelineStoppedException 例外をスローします。その後、System.Management.Automation.Cmdlet.WriteObject、System.Management.Automation.Cmdlet.WriteError、またはその他のいくつかの API を呼び出そうとすると、これらの呼び出しによって、System.Management.Automation.PipelineStoppedException 例外がスローされます。

System.Management.Automation.PipelineStoppedException 例外は、パイプライン内の別のコマンドレットが終了エラーを報告した場合、ユーザーがパイプラインの停止を要求した場合、または何らかの理由でパイプラインが完了する前に停止された場合にも発生する可能性があります。コマンドレットは、開いているリソースまたはその内部状態をクリーンアップする必要がない限り、System.Management.Automation.PipelineStoppedException 例外をキャッチする必要はありません。

コマンドレットは、終了エラーを報告する前に、任意の数の出力オブジェクトまたは終了しないエラーを書き込むことができます。ただし、終了エラーはパイプラインを完全に停止し、それ以上の出力、終了エラー、または終了しないエラーは報告できません。

コマンドレット System.Management.Automation.Cmdlet.ThrowTerminatingError* を呼び出すことができるのは、System.Management.Automation.Cmdlet.BeginProcessing、System.Management.Automation.Cmdlet.ProcessRecord、または system.Management.Automation.Cmdlet.EndProcessing 入力処理メソッドを呼び出したスレッドからのみ実行できます。 System.Management.Automation.Cmdlet.ThrowTerminatingError* 呼び出したり、別のスレッドから System.Management.Automation.Cmdlet.WriteError をしたりしないでください。代わりに、エラーをメインスレッドに伝える必要があります。

System.Management.Automation.Cmdlet.BeginProcessing、System.Management.Automation.Cmdlet.ProcessRecord、または System.Management.Automation.Cmdlet.EndProcessing メソッドの実装で、コマンドレットが例外をスローする可能性があります。これらのメソッドからスローされた例外 (Windows PowerShell ホストを停止するいくつかの重大なエラー条件を除く) は、パイプラインを停止する終了エラーとして解釈されますが、Windows PowerShell 全体では解釈されません。 (これはメインコマンドレットスレッドにのみ適用されます。コマンドレットによって生成されたスレッドでキャッチされない例外は、一般に、Windows PowerShell ホストを停止します)。エラーレコードエラー状態に関する追加情報がエンドユーザーに提供されるため、例外をスローするのではなく、System.Management.Automation.Cmdlet.ThrowTerminatingError* を使用することをお勧めします。コマンドレットでは、すべての例外 (catch (Exception e)) のキャッチと処理に対するマネージドコードガイドラインを遵守する必要があります。既知の型と予期される型の例外のみをエラーレコードに変換します。