Write-Error
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 encerramento. 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 terminante, insira uma cadeia de caracteres de mensagem de erro, um objeto ErrorRecord ou um objeto Exception . Use os outros parâmetros de para preencher o registro de Write-Error
erro.
Os erros não terminativos gravam um erro no fluxo de erros, mas não interrompem o processamento de comandos. 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 a Throw
palavra-chave.
Para obter mais informações, consulte about_Throw.
Exemplos
Exemplo 1: Gravar 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 encerramento 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 opcional do parâmetro Message .
Exemplo 3: Gravar 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: Gravar 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 $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 encerramento. 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
- FecharErro
- Erro de dispositivo
- DeadlockDetected
- InvalidArgument
- Dados inválidos
- InvalidOperation
- InvalidResult
- Tipo inválido
- MetadataError
- NotImplemented
- NãoInstalado
- ObjectNotFound
- OperaçãoParada
- OperationTimeout
- Erro de sintaxe
- ParserError
- PermissionDenied
- ResourceBusy
- ResourceExists
- RecursoIndisponível
- Erro de leitura
- Erro de gravação
- FromStdErr
- SecurityError
- ProtocolError
- Erro de conexão
- AuthenticationError
- LimitesExcedidos
- QuotaExceeded
- NotEnabled
Para obter informações sobre as categorias de erro, consulte Enumeração ErrorCategory.
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: | 0 |
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: | 0 |
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 canalizar 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 executar para resolver 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
Você pode canalizar uma cadeia de caracteres que contém uma mensagem de erro para esse cmdlet.
Saídas
None
Esse cmdlet não retorna nenhuma saída. Ele só grava 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().
Links Relacionados
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de