Relatório de erros do cmdlet
Os cmdlets devem relatar erros de forma diferente, dependendo se os erros estão encerrando erros ou erros não finalização. Erros de encerramento são erros que fazem com que o pipeline seja encerrado imediatamente ou erros que ocorrem quando não há motivo para continuar o processamento. Erros não finalização são os erros que relatam uma condição de erro atual, mas o cmdlet pode continuar a processar objetos de entrada. Com erros não finalizados, o usuário normalmente é notificado sobre o problema, mas o cmdlet continua a processar o próximo objeto de entrada.
Erros de terminação e não terminação
As diretrizes a seguir podem ser usadas para determinar se uma condição de erro é um erro de encerramento ou um erro não final.
A condição de erro impede que o cmdlet processe com êxito quaisquer outros objetos de entrada? Nesse caso, esse é um erro de encerramento.
A condição de erro está relacionada a um objeto de entrada específico ou a um subconjunto de objetos de entrada? Nesse caso, esse é um erro não determinação.
O cmdlet aceita vários objetos de entrada, de forma que o processamento possa ser bem-sucedido em outro objeto de entrada? Nesse caso, esse é um erro não determinação.
Os cmdlets que podem aceitar vários objetos de entrada devem decidir entre o que são erros de terminação e não terminação, mesmo quando uma situação específica se aplica a apenas um único objeto de entrada.
Os cmdlets podem receber qualquer número de objetos de entrada e enviar qualquer número de objetos de êxito ou erro antes de lançar uma exceção de encerramento. Não há nenhuma relação entre o número de objetos de entrada recebidos e o número de objetos de êxito e de erro enviados.
Os cmdlets que podem aceitar apenas objetos de entrada de 0 a 1 e gerar apenas objetos de saída de 0 a 1 devem tratar erros como erros de encerramento e gerar exceções de encerramento.
Relatando erros não roteando
O relatório de um erro não terminativo sempre deve ser feito dentro da implementação do cmdlet do método System.Management.Automation.Cmdlet.BeginProcessing, do método System.Management.Automation.Cmdlet.ProcessRecord ou do método System.Management.Automation.Cmdlet.EndProcessing. Esses tipos de erros são relatados chamando o método System.Management.Automation.Cmdlet.WriteError que, por sua vez, envia um registro de erro para o fluxo de erros.
Relatando erros de encerramento
Os erros de encerramento são relatados ao lançar exceções ou chamar o método System.Management.Automation.Cmdlet.ThrowTer automationError. Esteja ciente de que os cmdlets também podem capturar e relinhar exceções, como OutOfMemory, no entanto, eles não são necessários para relinhar exceções, pois o runtime do PowerShell também as capturará.
Você também pode definir suas próprias exceções para problemas específicos de sua situação ou adicionar informações adicionais a uma exceção existente usando seu registro de erro.
Registros de erro
O PowerShell descreve uma condição de erro não fatal com objetos System.Management.Automation.ErrorRecord. Cada objeto fornece informações de categoria de erro, um objeto de destino opcional e detalhes sobre a condição de erro.
Identificadores de erro
O identificador de erro é uma cadeia de caracteres simples que identifica a condição de erro dentro do cmdlet . O PowerShell combina esse identificador com um identificador de cmdlet para criar um identificador de erro totalmente qualificado que pode ser usado posteriormente ao filtrar fluxos de erro ou erros de log, ao responder a erros específicos ou a outras atividades específicas do usuário.
As diretrizes a seguir devem ser seguidas ao especificar identificadores de erro:
Atribua identificadores de erro diferentes, altamente específicos a caminhos de código diferentes. Cada caminho de código que chama System.Management.Automation.Cmdlet.WriteError ou System.Management.Automation.Cmdlet.ThrowTererror deve ter seu próprio identificador de erro.
Os identificadores de erro devem ser exclusivos para tipos de exceção do CLR (Common Language Runtime) para erros de encerramento e não finalização.
Não altere a semântica de um identificador de erro entre as versões do cmdlet ou do provedor do PowerShell. Depois que a semântica de um identificador de erro for estabelecida, ela deverá permanecer constante durante todo o ciclo de vida do cmdlet.
Para encerrar erros, use um identificador de erro exclusivo para um tipo de exceção CLR específico. Se o tipo de exceção mudar, use um novo identificador de erro.
Para erros de nãoterminação, use um identificador de erro específico para um objeto de entrada específico.
Escolha o texto para o identificador que corresponde tersely ao erro que está sendo relatado. Não use espaço em branco ou pontuação.
Não gere identificadores de erro que não sejam reproduzíveis. Por exemplo, não gere identificadores que incluam um identificador de processo. Identificadores de erro são úteis somente quando correspondem a identificadores vistos por outros usuários que estão enfrentando o mesmo problema.
Categorias de erro
As categorias de erro são usadas para agrupar erros para o usuário. O PowerShell define essas categorias e cmdlets e os provedores do PowerShell devem escolher entre elas ao gerar o registro de erro.
Para ver uma descrição das categorias de erro disponíveis, consulte a enumeração System.Management.Automation.ErrorCategory. Em geral, você deve evitar usar NoError, UndefinedError e GenericError sempre que possível.
Os usuários podem exibir erros com base na categoria quando são definidos $ErrorView como CategoryView.
Confira também
Comentários
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, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de