Windows PowerShell エラーレコード

2025-03-25

コマンドレットは、終了エラーと終了しないエラーのエラー状態を識別する System.Management.Automation.ErrorRecord オブジェクトを渡す必要があります。

System.Management.Automation.ErrorRecord オブジェクトには、次の情報が含まれています。

エラーを説明する例外。多くの場合、これはコマンドレットがキャッチしてエラーレコードに変換する例外です。すべてのエラーレコードに例外が含まれている必要があります。

コマンドレットが例外をキャッチしなかった場合は、新しい例外を作成し、エラー条件を最もよく表す例外クラスを選択する必要があります。ただし、System.Management.Automation.ErrorRecord オブジェクトの System.Management.Automation.ErrorRecord.Exception プロパティを介してアクセスできるため、例外をスローする必要はありません。

特定のエラーハンドラーで特定のエラー状態を処理するために、診断目的や Windows PowerShell スクリプトで使用できる対象指定子を提供するエラー識別子。すべてのエラーレコードには、エラー識別子が含まれている必要があります (エラー識別子を参照してください)。
診断目的で使用できる一般的な指定子を提供するエラーカテゴリ。すべてのエラーレコードでエラーカテゴリを指定する必要があります (エラーカテゴリを参照)。
オプションの置換エラーメッセージと推奨されるアクション (置換エラーメッセージを参照)。
エラーをスローしたコマンドレットに関する省略可能な呼び出し情報。この情報は、Windows PowerShell で指定されます (呼び出しメッセージを参照)。
エラーが発生したときに処理されていたターゲットオブジェクト。これは入力オブジェクトであるか、コマンドレットが処理していた別のオブジェクトである可能性があります。たとえば、コマンド Remove-Item -Recurse C:\somedirectoryの場合、エラーは "C:\somedirectory\lockedfile" の FileInfo オブジェクトのインスタンスである可能性があります。ターゲットオブジェクト情報は省略可能です。

エラー識別子

エラーレコードを作成するときに、コマンドレット内のエラー条件を指定する識別子を指定します。 Windows PowerShell は、対象の識別子とコマンドレットの名前を組み合わせて、完全修飾エラー識別子を作成します。完全修飾エラー識別子には、System.Management.Automation.ErrorRecord オブジェクトの System.Management.Automation.ErrorRecord.FullyQualifiedErrorId プロパティを使用してアクセスできます。エラー識別子は単独では使用できません。完全修飾エラー識別子の一部としてのみ使用できます。

エラーレコードを作成するときにエラー識別子を生成するには、次のガイドラインを使用します。

エラー条件に固有のエラー識別子を作成します。特定のエラーハンドラーを使用して特定のエラー状態を処理する診断目的とスクリプトのエラー識別子を対象とします。ユーザーはエラー識別子を使用して、エラーとそのソースを識別できる必要があります。また、エラー識別子を使用すると、既存の例外からの特定のエラー条件に対するレポートが有効になるため、新しい例外サブクラスは必要ありません。
一般に、異なるコードパスに異なるエラー識別子を割り当てます。エンドユーザーは、特定の識別子からメリットを得られます。多くの場合、System.Management.Automation.Cmdlet.WriteError または System.Management.Automation.Cmdlet.ThrowTerminatingError* を呼び出す各コードパスには、独自の識別子があります。原則として、エラーメッセージの新しいテンプレート文字列を定義するときに新しい識別子を定義します。その逆も同様です。エラーメッセージを識別子として使用しないでください。
特定のエラー識別子を使用してコードを発行する場合は、完全な製品サポートライフサイクルに対して、その識別子を使用してエラーのセマンティクスを確立します。元のコンテキストとは意味的に異なるコンテキストでは再利用しないでください。このエラーのセマンティクスが変更された場合は、新しい識別子を作成して使用します。
通常、特定の CLR 型の例外に対してのみ、特定のエラー識別子を使用する必要があります。例外の型またはターゲットオブジェクトの型が変更された場合は、新しい識別子を作成して使用します。
報告するエラーに簡潔に対応するエラー識別子のテキストを選択します。標準の .NET Framework の名前付け規則と大文字と小文字の表記規則を使用します。空白や句読点は使用しないでください。エラー識別子をローカライズしないでください。
再現不可能な方法でエラー識別子を動的に生成しないでください。たとえば、プロセス ID などのエラー情報を組み込む必要はありません。エラー識別子は、同じエラー状態が発生している他のユーザーによって表示されるエラー識別子に対応する場合にのみ役立ちます。

エラーカテゴリ

エラーレコードを作成するときは、System.Management.Automation.ErrorCategory 列挙体で定義されている定数のいずれかを使用して、エラーのカテゴリを指定します。 Windows PowerShell では、ユーザーが $ErrorView 変数を "CategoryView"に設定すると、エラーカテゴリを使用してエラー情報が表示されます。

System.Management.Automation.ErrorCategoryNotSpecified 定数は使用しないでください。エラーまたはエラーの原因となった操作に関する情報がある場合は、カテゴリが完全に一致しない場合でも、エラーまたは操作を最もよく説明するカテゴリを選択します。

Windows PowerShell によって表示される情報はカテゴリビュー文字列と呼ばれ、System.Management.Automation.ErrorCategoryInfo クラスのプロパティから構築されます。 (このクラスは、System.Management.Automation.ErrorRecord.CategoryInfo プロパティエラーによってアクセスされます)。

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

次の一覧では、表示される情報について説明します。

カテゴリ: Windows PowerShell で定義 System.Management.Automation.ErrorCategory 定数。
TargetName: 既定では、エラーが発生したときにコマンドレットが処理していたオブジェクトの名前。または、別のコマンドレットで定義された文字列です。
TargetType: 既定では、ターゲットオブジェクトの型です。または、別のコマンドレットで定義された文字列です。
アクティビティ: 既定では、エラーレコードを作成したコマンドレットの名前。または、コマンドレットで定義されたその他の文字列です。
理由: 既定では、例外の種類です。または、別のコマンドレットで定義された文字列です。

置換エラーメッセージ

コマンドレットのエラーレコードを開発する場合、エラーの既定のエラーメッセージは、System.Exception.Message プロパティの既定のメッセージテキストから取得されます。これは読み取り専用プロパティで、メッセージテキストはデバッグ目的でのみ使用されます (.NET Framework のガイドラインに従います)。既定のメッセージテキストを置換または拡張するエラーメッセージを作成することをお勧めします。メッセージをよりわかりやすいものにし、コマンドレットに固有にします。

置換メッセージは、System.Management.Automation.ErrorDetails オブジェクトによって提供されます。 Windows PowerShell で使用できる追加のローカライズ情報が提供されるため、このオブジェクトの次のいずれかのコンストラクターを使用します。

ErrorDetails(Cmdlet, String, String, Object[]): テンプレート文字列がコマンドレットが実装されているのと同じアセンブリ内のリソース文字列である場合、または System.Management.Automation.Cmdlet.GetResourceString メソッドのオーバーライドを使用してテンプレート文字列を読み込む場合は、このコンストラクターを使用します。
ErrorDetails(Assembly, String, String, Object[]): テンプレート文字列が別のアセンブリにあり、System.Management.Automation.Cmdlet.GetResourceStringのオーバーライドを介して読み込まない場合は、このコンストラクターを使用します。

置換メッセージは、小さな違いがある例外メッセージを書き込むための .NET Framework 設計ガイドラインに準拠している必要があります。このガイドラインでは、開発者向けに例外メッセージを記述する必要があることを示しています。これらの置換メッセージは、コマンドレットユーザーに対して書き込む必要があります。

置換エラーメッセージは、System.Management.Automation.Cmdlet.WriteError または system.Management.Automation.Cmdlet.ThrowTerminatingError* メソッドが呼び出される前に追加する必要があります。置換メッセージを追加するには、エラーレコード System.Management.Automation.ErrorRecord.ErrorDetails プロパティを設定します。このプロパティを設定すると、Windows PowerShell は既定のメッセージテキストではなく、System.Management.Automation.ErrorDetails.Message* プロパティを表示します。

推奨されるアクション情報

System.Management.Automation.ErrorDetails オブジェクトは、エラー発生時に推奨されるアクションに関する情報を提供することもできます。

呼び出し情報

コマンドレットが System.Management.Automation.Cmdlet.WriteError または System.Management.Automation.Cmdlet.ThrowTerminatingError* を使用してエラーレコードを報告する場合、Windows PowerShell は、エラーが発生したときに呼び出されたコマンドを説明する情報を自動的に追加します。この情報は、コマンドによって呼び出されたコマンドレットの名前、コマンド自体、およびパイプラインまたはスクリプトに関する情報を含む、System.Management.Automation.InvocationInfo オブジェクトによって提供されます。このプロパティは読み取り専用です。