Partilhar via

Registros de erro do Windows PowerShell

Os cmdlets devem passar um objeto System.Management.Automation.ErrorRecord que identifique a condição de erro para erros de encerramento e não encerramento.

O objeto System.Management.Automation.ErrorRecord contém as seguintes informações:

  • A exceção que descreve o erro. Muitas vezes, essa é uma exceção que o cmdlet detetou e converteu em um registro de erro. Cada registro de erro deve conter uma exceção.

Se o cmdlet não capturar uma exceção, ele deverá criar uma nova exceção e escolher a classe de exceção que melhor descreve a condição de erro. No entanto, você não precisa lançar a exceção porque ela pode ser acessada por meio da propriedade System.Management.Automation.ErrorRecord.Exception do objeto System.Management.Automation.ErrorRecord.

  • Um identificador de erro que fornece um designador de destino que pode ser usado para fins de diagnóstico e por scripts do Windows PowerShell para lidar com condições de erro específicas com manipuladores de erro específicos. Cada registro de erro deve conter um identificador de erro (consulte Identificador de erro).

  • Uma categoria de erro que fornece um designador geral que pode ser usado para fins de diagnóstico. Cada registro de erro deve especificar uma categoria de erro (consulte Categoria de erro).

  • Uma mensagem de erro de substituição opcional e uma ação recomendada (consulte Mensagem de erro de substituição).

  • Informações de invocação opcionais sobre o cmdlet que gerou o erro. Essas informações são especificadas pelo Windows PowerShell (consulte Mensagem de invocação).

  • O objeto de destino que estava sendo processado quando o erro ocorreu. Esse pode ser o objeto de entrada ou pode ser outro objeto que seu cmdlet estava processando. Por exemplo, para o comando Remove-Item -Recurse C:\somedirectory, o erro pode ser uma instância de um objeto FileInfo para "C:\somedirectory\lockedfile". As informações do objeto de destino são opcionais.

Identificador de erro

Ao criar um registro de erro, especifique um identificador que designe a condição de erro em seu cmdlet. O Windows PowerShell combina o identificador de destino com o nome do seu cmdlet para criar um identificador de erro totalmente qualificado. O identificador de erro totalmente qualificado pode ser acessado por meio da propriedade System.Management.Automation.ErrorRecord.FullyQualifiedErrorId do objeto System.Management.Automation.ErrorRecord. O identificador de erro não está disponível por si só. Ele está disponível apenas como parte do identificador de erro totalmente qualificado.

Use as seguintes diretrizes para gerar identificadores de erro ao criar registros de erro:

  • Crie identificadores de erro específicos para uma condição de erro. Direcione os identificadores de erro para fins de diagnóstico e para scripts que lidam com condições de erro específicas com manipuladores de erros específicos. Um utilizador deve poder utilizar o identificador de erro para identificar o erro e a sua origem. Os identificadores de erro também permitem a geração de relatórios para condições de erro específicas de exceções existentes, de modo que novas subclasses de exceção não sejam necessárias.

  • Em geral, atribua identificadores de erro diferentes a caminhos de código diferentes. O utilizador final beneficia de identificadores específicos. Muitas vezes, cada caminho de código que chama System.Management.Automation.Cmdlet.WriteError ou System.Management.Automation.Cmdlet.ThrowTerminatingError* tem seu próprio identificador. Como regra, defina um novo identificador ao definir uma nova cadeia de caracteres de modelo para a mensagem de erro e vice-versa. Não use a mensagem de erro como um identificador.

  • Ao publicar código usando um identificador de erro específico, você estabelece a semântica de erros com esse identificador para todo o ciclo de vida de suporte ao produto. Não o reutilize num contexto semanticamente diferente do contexto original. Se a semântica desse erro mudar, crie e use um novo identificador.

  • Geralmente, você deve usar um identificador de erro específico apenas para exceções de um tipo CLR específico. Se o tipo da exceção ou o tipo do objeto de destino mudar, crie e use um novo identificador.

  • Escolha texto para o identificador de erro que corresponda de forma concisa ao erro que você está relatando. Use convenções de nomenclatura e capitalização padrão do .NET Framework. Não use espaço em branco ou pontuação. Não localize identificadores de erro.

  • Não gere dinamicamente identificadores de erro de forma não reproduzível. Por exemplo, não incorpore informações de erro, como uma ID de processo. Os identificadores de erro são úteis somente se corresponderem aos identificadores de erro vistos por outros usuários que estão enfrentando a mesma condição de erro.

Categoria de Erro

Ao criar um registro de erro, especifique a categoria do erro usando uma das constantes definidas pelo System.Management.Automation.ErrorCategory enumeração. O Windows PowerShell usa a categoria de erro para exibir informações de erro quando os usuários definem a variável $ErrorView como "CategoryView".

Evite usar a constante System.Management.Automation.ErrorCategoryNotSpecified. Se você tiver alguma informação sobre o erro ou sobre a operação que causou o erro, escolha a categoria que melhor descreve o erro ou a operação, mesmo que a categoria não seja uma combinação perfeita.

As informações exibidas pelo Windows PowerShell são chamadas de cadeia de caracteres de exibição de categoria e são criadas a partir das propriedades da classe System.Management.Automation.ErrorCategoryInfo. (Essa classe é acessada por meio da propriedade de erro System.Management.Automation.ErrorRecord.CategoryInfo.)

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

A lista a seguir descreve as informações exibidas:

  • Categoria: Uma constante de System.Management.Automation.ErrorCategory definida pelo Windows PowerShell.

  • TargetName: Por padrão, o nome do objeto que o cmdlet estava processando quando o erro ocorreu. Ou, outra cadeia de caracteres definida por cmdlet.

  • TargetType: Por padrão, o tipo do objeto de destino. Ou, outra cadeia de caracteres definida por cmdlet.

  • Atividade: Por padrão, o nome do cmdlet que criou o registro de erro. Ou, alguma outra cadeia de caracteres definida por cmdlet.

  • Motivo: Por padrão, o tipo de exceção. Ou, outra cadeia de caracteres definida por cmdlet.

Mensagem de erro de substituição

Quando você desenvolve um registro de erro para um cmdlet, a mensagem de erro padrão para o erro vem do texto da mensagem padrão na propriedade System.Exception.Message. Esta é uma propriedade somente leitura cujo texto da mensagem se destina apenas para fins de depuração (de acordo com as diretrizes do .NET Framework). Recomendamos que você crie uma mensagem de erro que substitua ou aumente o texto da mensagem padrão. Torne a mensagem mais amigável e mais específica para o cmdlet.

A mensagem de substituição é fornecida por um objeto System.Management.Automation.ErrorDetails. Use um dos seguintes construtores deste objeto porque eles fornecem informações de localização adicionais que podem ser usadas pelo Windows PowerShell.

A mensagem de substituição deve estar em conformidade com as diretrizes de design do .NET Framework para escrever mensagens de exceção com uma pequena diferença. As diretrizes afirmam que as mensagens de exceção devem ser escritas para desenvolvedores. Essas mensagens de substituição devem ser gravadas para o usuário do cmdlet.

A mensagem de erro de substituição deve ser adicionada antes que os métodos System.Management.Automation.Cmdlet.WriteError ou System.Management.Automation.Cmdlet.ThrowTerminatingError* sejam chamados. Para adicionar uma mensagem de substituição, defina a propriedade System.Management.Automation.ErrorRecord.ErrorDetails do registro de erro. Quando essa propriedade é definida, o Windows PowerShell exibe a propriedade System.Management.Automation.ErrorDetails.Message* em vez do texto da mensagem padrão.

O objeto System.Management.Automation.ErrorDetails também pode fornecer informações sobre quais ações são recomendadas quando o erro ocorre.

Informações de invocação

Quando um cmdlet usa System.Management.Automation.Cmdlet.WriteError ou System.Management.Automation.Cmdlet.ThrowTerminatingError* para relatar um registro de erro, o Windows PowerShell adiciona automaticamente informações que descrevem o comando que foi invocado quando o erro ocorreu. Essas informações são fornecidas por um objeto System.Management.Automation.InvocationInfo que contém o nome do cmdlet que foi invocado pelo comando, o próprio comando e informações sobre o pipeline ou script. Esta propriedade é somente leitura.

Ver também

System.Management.Automation.Cmdlet.WriteError

System.Management.Automation.Cmdlet.ThrowTerminatingError*

System.Management.Automation.ErrorCategory

System.Management.Automation.ErrorCategoryInfo

System.Management.Automation.ErrorRecord

System.Management.Automation.ErrorDetails

System.Management.Automation.InvocationInfo

Relatório de Erros do Windows PowerShell

Escrevendo um cmdlet do Windows PowerShell

  • Last updated on