Compartilhar via

Registros de erros do Windows PowerShell

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

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

  • A exceção que descreve o erro. Geralmente, essa é uma exceção que o cmdlet capturou 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 erros específicos. Cada registro de erro deve conter um identificador de erro (consulte o 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 o 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 designa a condição de erro dentro do cmdlet. O Windows PowerShell combina o identificador de destino com o nome do 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:

  • Torne os identificadores de erro específicos a 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 usuário deve ser capaz de usar o identificador de erro para identificar o erro e sua origem. Os identificadores de erro também habilitam o relatório para condições de erro específicas de exceções existentes para que novas subclasses de exceção não sejam necessárias.

  • Em geral, atribua diferentes identificadores de erro a caminhos de código diferentes. O usuário final se beneficia de identificadores específicos. Geralmente, 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 quando você 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 o ciclo de vida completo do suporte ao produto. Não reutilize-o em um 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 do tipo do objeto de destino for alterado, crie e use um novo identificador.

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

  • Não gere identificadores de erro dinamicamente de maneira não reproduzível. Por exemplo, não incorpore informações de erro, como uma ID do processo. Os identificadores de erro serã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 do 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 correspondência perfeita.

As informações exibidas pelo Windows PowerShell são conhecidas como a 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 do erro propriedade System.Management.Automation.ErrorRecord.CategoryInfo.)

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

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

  • Categoria: uma constante 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 pelo cmdlet.

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

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

  • Motivo: por padrão, o tipo de exceção. Ou outra cadeia de caracteres definida pelo 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. Essa é uma propriedade somente leitura cujo texto da mensagem destina-se 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 desse objeto porque eles fornecem informações adicionais de localização 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 gravar mensagens de exceção com uma pequena diferença. As diretrizes afirmam que as mensagens de exceção devem ser gravadas 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, pelo próprio comando e informações sobre o pipeline ou script. Essa propriedade é somente leitura.

Consulte 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

gravando um cmdlet do Windows PowerShell

  • Last updated on