Compartilhar via

Write-Error

Módulo:
Microsoft.PowerShell.Utility Module

Grava um objeto no fluxo de erros.

Sintaxe

NoException (Default) 

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 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 no HKLM: ou HKCU: unidades 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 does not 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 .

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
  • Erro aberto
  • Erro de fechamento
  • Erro de dispositivo
  • DeadlockDetectado
  • InvalidArgument
  • Dados inválidos
  • Operação Inválida
  • Resultado inválido
  • TipoInválido
  • MetadadosError
  • Não Implementado
  • Não Instalado
  • ObjectNotFound
  • OperaçãoInterrompida
  • OperationTimeout
  • SintaxeError
  • ParserError
  • Permissão negada
  • Recurso ocupado
  • ResourceExists
  • RecursoIndisponível
  • Erro de leitura
  • Erro de gravação
  • FromStdErr
  • Erro de segurança
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • LimitesExcedidos
  • QuotaExceeded
  • NotEnabled

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

Propriedades do parâmetro

Tipo:ErrorCategory
Valor padrão:NotSpecified
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
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

NoException
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False
WithException
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-CategoryActivity

Especifica a ação que causou o erro.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False
Aliases:Atividade

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-CategoryReason

Especifica como ou por que a atividade causou o erro.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False
Aliases:Motivo

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-CategoryTargetName

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

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False
Aliases:Nome do alvo

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-CategoryTargetType

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

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False
Aliases:TipoDeAlvo

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-ErrorId

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

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

NoException
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False
WithException
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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.

Propriedades do parâmetro

Tipo:ErrorRecord
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

ErrorRecord
Cargo:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 do parâmetro

Tipo:Exception
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

WithException
Cargo:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False
Aliases:Msg

Conjuntos de parâmetros

NoException
Cargo:0
Obrigatório:True
Valor do pipeline:True
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False
WithException
Cargo:0
Obrigatório:True
Valor do pipeline:True
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-RecommendedAction

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

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 do parâmetro

Tipo:Object
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

NoException
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False
WithException
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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.