Partilhar via

Write-Error

Módulo:
Microsoft.PowerShell.Utility Module

Grava um objeto no fluxo de erro.

Sintaxe

NoException (Predefinição) 

Write-Error
    [-Message] <string>
    [-Category <ErrorCategory>]
    [-ErrorId <string>]
    [-TargetObject <Object>]
    [-RecommendedAction <string>]
    [-CategoryActivity <string>]
    [-CategoryReason <string>]
    [-CategoryTargetName <string>]
    [-CategoryTargetType <string>]
    [<CommonParameters>]

WithException 

Write-Error
    [-Exception] <Exception>
    [-Message <string>]
    [-Category <ErrorCategory>]
    [-ErrorId <string>]
    [-TargetObject <Object>]
    [-RecommendedAction <string>]
    [-CategoryActivity <string>]
    [-CategoryReason <string>]
    [-CategoryTargetName <string>]
    [-CategoryTargetType <string>]
    [<CommonParameters>]

ErrorRecord 

Write-Error
    [-ErrorRecord] <ErrorRecord>
    [-RecommendedAction <string>]
    [-CategoryActivity <string>]
    [-CategoryReason <string>]
    [-CategoryTargetName <string>]
    [-CategoryTargetType <string>]
    [<CommonParameters>]

Description

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.

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 cmdlet Get-ChildItem retorna um objeto Microsoft.Win32.RegistryKey, como os objetos nas unidades HKLM: ou HKCU: do 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 opcional Message nome do parâmetro.

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

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
  • Operação Inválida
  • InvalidResult
  • Tipo inválido
  • MetadataError
  • Não Implementado
  • NotInstalled
  • ObjectNotFound
  • OperaçãoInterrompida
  • OperationTimeout
  • SyntaxError
  • ParserError
  • PermissãoNegada
  • ResourceBusy
  • ResourceExists
  • RecursoIndisponível
  • ReadError
  • WriteError
  • FromStdErr
  • Erro de segurança
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • LimitesExcedidos
  • QuotaExcedido
  • NotEnabled

Para obter informações sobre as categorias de erro, consulte ErrorCategory Enumeration.

Propriedades dos parâmetros

Tipo:ErrorCategory
Default value:NotSpecified
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
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

NoException
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
WithException
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-CategoryActivity

Especifica a ação que causou o erro.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Atividade

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-CategoryReason

Especifica como ou por que a atividade causou o erro.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Motivo

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-CategoryTargetName

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

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Nome do alvo

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-CategoryTargetType

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

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Tipo de alvo

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-ErrorId

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

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

NoException
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
WithException
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 na variável automática $Error.

Propriedades dos parâmetros

Tipo:ErrorRecord
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

ErrorRecord
Position:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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.

Propriedades dos parâmetros

Tipo:Exception
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

WithException
Position:0
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Msg

Conjuntos de parâmetros

NoException
Position:0
Obrigatório:True
Valor do pipeline:True
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
WithException
Position:0
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-RecommendedAction

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

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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.

Propriedades dos parâmetros

Tipo:Object
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

NoException
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
WithException
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

CommonParameters

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.

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