Write-Error

Sintaxe

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

Description

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

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

Erros não terminantes gravam um erro no fluxo de erros, mas não interrompem o processamento de comandos. Se um erro não fatal for declarado em um item em uma coleção de itens de entrada, o comando continuará a processar os outros itens na coleção.

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

Exemplos

Exemplo 1: Escrever um erro para o objeto RegistryKey

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

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

Exemplo 2: Gravar uma mensagem de erro no console

Write-Error "Access denied."

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

Exemplo 3: Escreva um erro no console e especifique a categoria

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

Esse comando declara um erro não fatal e especifica uma categoria de erro.

Exemplo 4: Escrever um erro usando um objeto 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."

Esse comando usa um objeto Exception para declarar um erro de não encerramento.

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

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

Parâmetros

-Category

-CategoryActivity

-CategoryReason

-CategoryTargetName

-CategoryTargetType

-ErrorId

-ErrorRecord

-Exception

-Message

-RecommendedAction

-TargetObject

Entradas

String

Você pode canalizar uma cadeia de caracteres que contém uma mensagem de erro para esse cmdlet.

Saídas

None

Esse cmdlet não retorna nenhuma saída. Ele grava apenas no fluxo de mensagens de erro.

Observações

Write-Error não altera o valor da variável automática, portanto, não sinaliza uma condição de $? erro de encerramento. Para sinalizar um erro de encerramento, use o método $PSCmdlet.WriteError().

Links Relacionados

• about_Automatic_Variables
• about_Output_Streams
• about_Redirection
• Write-Debug
• Write-Host
• Write-Output
• Write-Progress
• Write-Verbose
• Write-Warning