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
    {
        $_
    }
}

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

例 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 does not 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 列挙型」を参照してください。

Type:	ErrorCategory
Accepted values:	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
Position:	Named
Default value:	NotSpecified
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryActivity

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

Type:	String
Aliases:	Activity
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryReason

アクティビティがエラーの原因となった方法または理由を指定します。

Type:	String
Aliases:	Reason
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryTargetName

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

Type:	String
Aliases:	TargetName
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryTargetType

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

Type:	String
Aliases:	TargetType
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-ErrorId

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

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-ErrorRecord

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

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

Type:	ErrorRecord
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Exception

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

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

Type:	Exception
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Message

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

Type:	String
Aliases:	Msg
Position:	0
Default value:	None
Accept pipeline input:	True
Accept wildcard characters:	False

-RecommendedAction

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

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-TargetObject

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

Type:	Object
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

入力

String

エラーメッセージ Write-Errorを含む文字列をパイプ処理できます。

出力

Error object

Write-Error はエラーストリームにのみ書き込みます。このコマンドはオブジェクトを返しません。

メモ

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