次の方法で共有

Write-Error

  • リファレンス
モジュール:
Microsoft.PowerShell.Utility

エラー ストリームにオブジェクトを書き込みます。

構文

Write-Error
     [-Message] <string>
     [-Category <ErrorCategory>]
     [-ErrorId <string>]
     [-TargetObject <Object>]
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]
Write-Error
     -Exception <Exception>
     [-Message <string>]
     [-Category <ErrorCategory>]
     [-ErrorId <string>]
     [-TargetObject <Object>]
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]
Write-Error
     -ErrorRecord <ErrorRecord>
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]

説明

Write-Error コマンドレットは、終了しないエラーを宣言します。 既定では、エラー ストリームで出力と共に表示されるホスト プログラムにエラーが送信されます。

終了しないエラーを書き込むには、エラー メッセージ文字列、 ErrorRecord オブジェクト、または Exception オブジェクトを入力します。 エラー レコードを設定するには、 Write-Error の他のパラメーターを使用します。

終了しないエラーはエラー ストリームにエラーを書き込みますが、コマンド処理は停止しません。 未終了エラーが、入力項目のコレクション内の 1 つの項目で宣言された場合、コマンドはコレクション内の他の項目の処理を続行します。

終了エラーを宣言するには、 Throw キーワードを使用します。 詳細については、「 about_Throw」を参照してください。

例

例 1: RegistryKey オブジェクトのエラーを書き込む

Get-ChildItem | ForEach-Object {
    if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
    {
        Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
    }
    else
    {
        $_
    }
}

このコマンドは、Get-ChildItem コマンドレットが powerShell レジストリ プロバイダーのHKLM:またはHKCU: ドライブ内のオブジェクトなどのMicrosoft.Win32.RegistryKey オブジェクトを返すときに、終了しないエラーを宣言します。

例 2: コンソールにエラー メッセージを書き込む

Write-Error "Access denied."

このコマンドは、未終了エラーを宣言し、"Access denied" エラーを書き込みます。 このコマンドでは、 Message パラメーターを使用してメッセージを指定しますが、省略可能な Message パラメーター名は省略します。

例 3: コンソールにエラーを書き込み、カテゴリを指定する

Write-Error -Message "Error: Too many input values." -Category InvalidArgument

このコマンドは、未終了エラーを宣言し、エラー カテゴリを書き込みます。

例 4: Exception オブジェクトを使用してエラーを書き込む

$E = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="https://go.microsoft.com/fwlink/?LinkID=113425"}
Write-Error -Exception $E -Message "Files not found. The $Files location doesn't contain any XML files."

このコマンドは、 Exception オブジェクトを使用して、終了しないエラーを宣言します。

最初のコマンドでは、ハッシュ テーブルを使用して、 System.Exception オブジェクトを作成します。 例外オブジェクトを $E 変数に保存します。 ハッシュ テーブルを使用して、null コンストラクターを持つ種類のオブジェクトを作成します。

2 番目のコマンドでは、 Write-Error コマンドレットを使用して、終了しないエラーを宣言します。 Exception パラメーターの値は、$E変数のException オブジェクトです。

パラメーター

-Category

エラーのカテゴリを指定します。 既定値は NotSpecified です。 このパラメーターの有効値は、次のとおりです。

  • NotSpecified
  • OpenError
  • CloseError
  • DeviceError
  • DeadlockDetected
  • InvalidArgument
  • InvalidData
  • InvalidOperation
  • InvalidResult
  • InvalidType
  • MetadataError
  • NotImplemented
  • NotInstalled
  • ObjectNotFound
  • OperationStopped
  • OperationTimeout
  • SyntaxError
  • ParserError
  • PermissionDenied
  • ResourceBusy
  • ResourceExists
  • ResourceUnavailable
  • ReadError
  • WriteError
  • FromStdErr
  • SecurityError
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • LimitsExceeded
  • QuotaExceeded
  • NotEnabled

エラー カテゴリの詳細については、「 ErrorCategory 列挙型を参照してください。

型:ErrorCategory
指定可能な値:NotSpecified, OpenError, CloseError, DeviceError, DeadlockDetected, InvalidArgument, InvalidData, InvalidOperation, InvalidResult, InvalidType, MetadataError, NotImplemented, NotInstalled, ObjectNotFound, OperationStopped, OperationTimeout, SyntaxError, ParserError, PermissionDenied, ResourceBusy, ResourceExists, ResourceUnavailable, ReadError, WriteError, FromStdErr, SecurityError, ProtocolError, ConnectionError, AuthenticationError, LimitsExceeded, QuotaExceeded, NotEnabled
配置:Named
規定値:NotSpecified
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-CategoryActivity

エラーの原因となったアクションを指定します。

型:String
Aliases:Activity
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-CategoryReason

アクティビティによってエラーが発生した方法または理由を指定します。

型:String
Aliases:Reason
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-CategoryTargetName

エラーが発生したときに処理されていたオブジェクトの名前を指定します。

型:String
Aliases:TargetName
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-CategoryTargetType

エラーが発生したときに処理されていたオブジェクトの種類を指定します。

型:String
Aliases:TargetType
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-ErrorId

エラーを識別する ID 文字列を指定します。 この文字列、はエラーに対して一意である必要があります。

型:String
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-ErrorRecord

エラーを表す エラー レコード オブジェクトを指定します。 エラーを説明するオブジェクトのプロパティを使用します。

エラー レコード オブジェクトを作成するには、 New-Object コマンドレットを使用するか、 $Error 自動変数の配列からエラー レコード オブジェクトを取得します。

型:ErrorRecord
配置:Named
規定値:None
必須:True
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Exception

エラーを表す例外オブジェクトを指定します。 エラーを説明するオブジェクトのプロパティを使用します。

例外オブジェクトを作成するには、ハッシュ テーブルを使用するか、 New-Object コマンドレットを使用します。

型:Exception
配置:Named
規定値:None
必須:True
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Message

エラーのメッセージ テキストを指定します。 テキストにスペースまたは特殊文字が含まれる場合は、二重引用符で囲みます。 メッセージ文字列をパイプして Write-Errorすることもできます。

型:String
Aliases:Msg
配置:0
規定値:None
必須:False
パイプライン入力を受け取る:True
ワイルドカード文字を受け取る:False

-RecommendedAction

エラーを解決または回避するためにユーザーが実行する必要があるアクションを指定します。

型:String
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-TargetObject

エラーが発生したときに処理されていたオブジェクトを指定します。 オブジェクト、オブジェクトを含む変数、またはオブジェクトを取得するコマンドを入力します。

型:Object
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

入力

String

エラー メッセージを含む文字列をこのコマンドレットにパイプできます。

出力

None

このコマンドレットは、出力を返しません。 エラー メッセージ ストリームにのみ書き込まれます。

メモ

Write-Error は、 $? 自動変数の値を変更しないため、終了エラー状態を通知しません。 終了エラーを通知するには、 $PSCmdlet.WriteError() メソッドを使用します。