Compartilhar via

Write-Error

Módulo:
Microsoft.PowerShell.Utility Module

Grava um objeto no fluxo de erros.

Sintaxe

NoException (Padrã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 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 .

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:0
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:0
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:False
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 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().