Share via

Write-Error

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

Grava um objeto no fluxo de erros.

Syntax

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 serão enviados no fluxo de erros para o programa do host para serem exibidos, juntamente com a saída.

Para gravar um erro não fatal, digite uma cadeia de caracteres de mensagem de erro, um objeto ErrorRecord ou um Exception. Use os outros parâmetros de Write-Error para preencher o registro de erro.

Erros não fatais gravam um erro no fluxo de erros, mas não param o processamento do comando. Se um erro não fatal for declarado em um item em uma coleção de itens de entrada, o comando continuará a processar os outros itens na coleção.

Para declarar um erro de encerramento, use o 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
    {
        $_
    }
}

Esse comando declara um erro de não terminação quando o Get-ChildItem cmdlet retorna um Microsoft.Win32.RegistryKey objeto, como os objetos nas HKLM: unidades 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 não fatal 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: escrever um erro no console e especificar a categoria

Write-Error -Message "Error: Too many input values." -Category InvalidArgument

Esse comando declara um erro não fatal 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 fatal.

O primeiro comando usa uma tabela de hash para criar o objeto System.Exception. Ele salva o objeto de exceção na $E variável. Você pode usar uma tabela de hash para criar qualquer objeto de um tipo que possui um construtor nulo.

O segundo comando usa o Write-Error cmdlet para declarar um erro de não terminação. 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 esse parâmetro são:

  • NotSpecified
  • OpenError
  • CloseError
  • DeviceError
  • DeadlockDetected
  • InvalidArgument
  • InvalidData
  • InvalidOperation
  • InvalidResult
  • InvalidType
  • MetadadosError
  • NotImplemented
  • NotInstalled
  • ObjectNotFound
  • OperationStopped
  • OperationTimeout
  • Syntaxerror
  • Parsererror
  • PermissionDenied
  • ResourceBusy
  • ResourceExists
  • ResourceUnavailable
  • ReadError
  • WriteError
  • FromStdErr
  • SecurityError
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • LimitsExceeded
  • QuotaExceeded
  • NotEnabled

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

Type:ErrorCategory
Accepted values: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
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CategoryActivity

Especifica a ação que causou o erro.

Type:String
Aliases:Activity
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CategoryReason

Especifica como ou por que a atividade causou o erro.

Type:String
Aliases:Reason
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CategoryTargetName

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

Type:String
Aliases:TargetName
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CategoryTargetType

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

Type:String
Aliases:TargetType
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ErrorId

Especifica uma cadeia de caracteres de identificação para identificar o erro. A cadeia de caracteres deve ser exclusiva para o erro.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ErrorRecord

Especifica um objeto de registro de erro que representa o erro. Usa 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.

Type:ErrorRecord
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Exception

Especifica um objeto de exceção que representa o erro. Usa as propriedades do objeto para descrever o erro.

Para criar um objeto de exceção, use uma tabela de hash ou use o New-Object cmdlet .

Type:Exception
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Message

Especifica o texto da mensagem de erro. Se a expressão incluir espaços ou caracteres especiais, coloque-a entre aspas. Você também pode redirecionar uma cadeia de caracteres de mensagem para Write-Error.

Type:String
Aliases:Msg
Position:0
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-RecommendedAction

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

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 .

Type:Object
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

String

Você pode redirecionar 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.

Observações

Write-Error não altera o valor da $? variável automática, portanto, ela não sinaliza uma condição de erro de encerramento. Para sinalizar um erro de encerramento, use o método $PSCmdlet.WriteError().