Write-Error

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>]

O cmdlet Write-Error declara um erro não terminativo. Por padrão, os erros são enviados no fluxo de erros para o programa host a ser exibido, juntamente com a saída.

Para escrever um erro não terminativo, insira uma cadeia de caracteres de mensagem de erro, um objeto ErrorRecord ou um objeto Exception . Use os outros parâmetros do Write-Error para preencher o registro de erro.

Os erros que não terminam gravam um erro no fluxo de erros, mas não interrompem o processamento de comandos. Se um erro não terminativo for declarado em um item em uma coleção de itens de entrada, o comando continuará a processar os outros itens da coleção.

Para declarar um erro de encerramento, use a palavra-chave Throw. Para obter mais informações, consulte about_Throw.

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

Este comando declara um erro não terminativo quando o cmdlet Get-ChildItem retorna um objeto Microsoft.Win32.RegistryKey, como os objetos nas unidades HKLM: ou HKCU: do provedor de Registro do PowerShell.

Write-Error "Access denied."

Este comando declara um erro de não terminação e grava um erro "Acesso negado". O comando usa o parâmetro Message para especificar a mensagem, mas omite o opcional Message nome do parâmetro.

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

Este comando declara um erro não terminativo e especifica uma categoria de erro.

$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."

Este comando usa um objeto Exception para declarar um erro não terminativo.

O primeiro comando usa uma tabela de hash para criar o objeto System.Exception. Ele salva o objeto de exceção na variável $E. Você pode usar uma tabela de hash para criar qualquer objeto de um tipo que tenha um construtor nulo.

O segundo comando usa o cmdlet Write-Error para declarar um erro não terminativo. O valor do parâmetro Exception é o objeto Exception na variável $E.

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Você pode canalizar uma cadeia de caracteres que contém uma mensagem de erro para Write-Error.

Write-Error grava somente no fluxo de erros. Ele não retorna nenhum objeto.