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

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:Named
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:Named
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:True
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 Write-Error.

Saídas

Error object

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