Compartilhar via

Write-Error

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Grava um objeto no fluxo de erros.

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 cmdlet Write-Error declara um erro de não encerramento. 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 de não terminação, insira uma cadeia de caracteres de mensagem de erro, um objeto ErrorRecord ou um objeto de exceção. Use os outros parâmetros de Write-Error para preencher o registro de erro.

Erros de não término gravam um erro no fluxo de erros, mas não interrompem o processamento de comandos. Se um erro de não encerramento for declarado em um item em uma coleção de itens de entrada, o comando continuará processando os outros itens na coleção.

Para declarar um erro de encerramento, use a palavra-chave Throw. 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 terminação quando o cmdlet Get-ChildItem retorna um objeto Microsoft.Win32.RegistryKey, como os objetos nas unidades HKLM: 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 de não encerramento e grava um erro "Acesso negado". O comando usa o parâmetro Message para especificar a mensagem, mas omite o nome do parâmetro de mensagem opcional.

Exemplo 3: escrever um erro no console e especificar a categoria

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

Esse comando declara um erro de não encerramento 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 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 de não terminação. O valor do parâmetro de Exceção é o objeto de Exceção na variável $E.

Parâmetros

-Category

Especifica a categoria do erro. O valor padrão é NotSpecified . Os valores aceitáveis para este parâmetro são:

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

Para obter informações sobre as categorias de erro, consulte de Enumeração ErrorCategory.

Tipo:ErrorCategory
Valores aceitos: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
Cargo:Named
Valor padrão:NotSpecified
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CategoryActivity

Especifica a ação que causou o erro.

Tipo:String
Aliases:Activity
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CategoryReason

Especifica como ou por que a atividade causou o erro.

Tipo:String
Aliases:Reason
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CategoryTargetName

Especifica o nome do objeto que estava sendo processado quando o erro ocorreu.

Tipo:String
Aliases:TargetName
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CategoryTargetType

Especifica o tipo do objeto que estava sendo processado quando o erro ocorreu.

Tipo:String
Aliases:TargetType
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ErrorId

Especifica uma cadeia de caracteres de ID para identificar o erro. A cadeia de caracteres deve ser exclusiva do erro.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ErrorRecord

Especifica um objeto de registro de erro que representa o erro. Use as propriedades do objeto para descrever o erro.

Para criar um objeto de registro de erro, use o cmdlet New-Object ou obtenha um objeto de registro de erro da matriz no $Error variável automática.

Tipo:ErrorRecord
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Exception

Especifica um objeto de exceção que representa o erro. Use as propriedades do objeto para descrever o erro.

Para criar um objeto de exceção, use uma tabela de hash ou use o cmdlet New-Object.

Tipo:Exception
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Message

Especifica o texto da mensagem do erro. Se o texto incluir espaços ou caracteres especiais, coloque-o entre aspas. Você também pode redirecionar uma cadeia de caracteres de mensagem para Write-Error.

Tipo:String
Aliases:Msg
Cargo:0
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-RecommendedAction

Especifica a ação que o usuário deve tomar para resolver ou impedir o erro.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-TargetObject

Especifica o objeto que estava sendo processado quando o erro ocorreu. Insira o objeto, uma variável que contém o objeto ou um comando que obtém o objeto.

Tipo:Object
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

String

Você pode canalizar uma cadeia de caracteres que contém uma mensagem de erro para este 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().