Partilhar via

Write-Error

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

Grava um objeto no fluxo de erro.

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 terminação. 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 de para preencher o registro de Write-Error 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 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
    {
        $_
    }
}

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

Exemplo 2: Escrever uma mensagem de erro na consola

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

Este comando declara um erro não terminativo 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."

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

O primeiro comando utiliza uma tabela hash para criar o objeto System.Exception. Ele salva o objeto de exceção na $E variável. Pode utilizar uma tabela hash para criar qualquer objeto de um tipo que tenha um construtor null.

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

Parâmetros

-Category

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

  • Não especificado
  • OpenError
  • FecharErro
  • DeviceError
  • DeadlockDetected
  • InvalidArgument
  • Dados inválidos
  • InvalidOperation
  • InvalidResult
  • Tipo inválido
  • MetadataError
  • NãoImplementado
  • NotInstalled
  • ObjectNotFound
  • OperaçãoInterrompida
  • OperationTimeout
  • SyntaxError
  • ParserError
  • PermissãoNegada
  • ResourceBusy
  • ResourceExists
  • RecursoIndisponível
  • ReadError
  • WriteError
  • FromStdErr
  • Erro de segurança
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • LimitesExcedidos
  • QuotaExceeded
  • NotEnabled

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

Tipo:ErrorCategory
Valores aceites: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
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CategoryActivity

Especifica a ação que causou o erro.

Tipo:String
Aliases:Activity
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CategoryReason

Especifica como ou por que a atividade causou o erro.

Tipo:String
Aliases:Reason
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CategoryTargetName

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

Tipo:String
Aliases:TargetName
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CategoryTargetType

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

Tipo:String
Aliases:TargetType
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ErrorId

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

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 New-Object cmdlet ou obtenha um objeto de registro de erro da matriz na $Error variável automática.

Tipo:ErrorRecord
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais: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, utilize uma tabela hash ou o cmdlet New-Object.

Tipo:Exception
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 canalizar uma cadeia de caracteres de mensagem para Write-Error.

Tipo:String
Aliases:Msg
Position:0
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-RecommendedAction

Especifica a ação que o usuário deve executar para resolver ou evitar o erro.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

String

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

Saídas

None

Este cmdlet não retorna nenhuma saída. Ele só grava no fluxo de mensagens de erro.

Notas

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().