Partilhar via

Tratamento de erros e valores retornados

  • Artigo

VSPackages e COM usam a mesma arquitetura para erros. As SetErrorInfo funções and GetErrorInfo fazem parte da API (interface de programação de aplicativo) do Win32. Qualquer VSPackage no IDE (ambiente de desenvolvimento integrado) pode chamar essas APIs globais do Win32 para registrar informações de erro avançadas ao receber uma notificação de erro. O SDK do Visual Studio fornece assemblies de interoperabilidade para gerenciar informações de erro.

Métodos de interoperabilidade

Como conveniência, o IDE fornece um método, SetErrorInfo, para usar em vez de chamar as APIs do Win32. No código gerenciado, use SetErrorInfo. Quando um erro HRESULT chega ao nível em que a mensagem de erro deve ser exibida (geralmente é o objeto que implementa um IOleCommandTarget manipulador de comandos), o IDE usa outro método, ReportErrorInfo, para exibir a caixa de mensagem apropriada. No código gerenciado, use o ReportErrorInfo método.

Como um implementador VSPackage, seus objetos COM normalmente implementam ISupportErrorInfo. A ISupportErrorInfo interface garante que informações de erro avançadas possam se mover verticalmente para cima na cadeia de chamadas. Os objetos que podem ser usados entre processos ou threads devem dar suporte ISupportErrorInfo para garantir que as informações de erro avançadas sejam empacotadas corretamente de volta para o chamador.

Todos os objetos relacionados a VSPackages e que estão envolvidos na extensão do IDE, incluindo fábricas de editores, editores, hierarquias e serviços oferecidos, devem oferecer suporte a informações de erro avançadas. Embora o IDE não exija que esses objetos VSPackage sejam implementados ISupportErrorInfo, ele é sempre incentivado.

O IDE é responsável por relatar informações de erro e exibi-las a um usuário do Visual Studio sempre que um HRESULT é propagado para o IDE. O IDE também é o mecanismo para criar ErrorInfo objetos.

Diretrizes gerais

Você também pode usar os SetErrorInfo métodos and ReportErrorInfo para definir e relatar erros internos à implementação do VSPackage. No entanto, como regra geral, siga estas diretrizes para lidar com mensagens de erro em seu VSPackage:

  • Implemente ISupportErrorInfo em seus objetos COM VSPackage.

  • Crie um mecanismo de relatório de erros que chame o SetErrorInfo método em objetos que implementam IOleCommandTarget.

  • Deixe o IDE exibir erros para os usuários por meio do ReportErrorInfo método.

Informações de erro no IDE

As regras a seguir indicam como lidar com informações de erro no IDE do Visual Studio:

  • Como uma estratégia defensiva para garantir que informações de erro obsoletas não sejam relatadas aos usuários, as funções que chamam o ReportErrorInfo método devem primeiro chamar o SetErrorInfo método. Passe para limpar as mensagens de erro armazenadas em null cache antes de chamar qualquer coisa que possa definir novas informações de erro.

  • As funções que não relatam mensagens de erro diretamente só têm permissão para chamar o SetErrorInfo método se estiverem retornando um erro HRESULT. É permitido limpar o ErrorInfo na entrada de uma função ou ao retornar S_OK. A única exceção a essa regra é quando uma chamada retorna um erro HRESULT do qual a parte receptora pode se recuperar explicitamente ou ignorar com segurança.

  • Qualquer parte que ignore explicitamente um erro HRESULT deve chamar o SetErrorInfo método com S_OK. Caso contrário, o ErrorInfo objeto pode ser usado acidentalmente quando outra parte gerar um erro sem fornecer seu próprio ErrorInfo.

  • Todos os métodos que originam um erro HRESULT são incentivados a chamar o SetErrorInfo método para fornecer informações de erro avançadas. Se o retornado HRESULT for um erro especial FACILITY_ITF , o método será necessário para fornecer um objeto adequado ErrorInfo . Se o erro retornado for um erro padrão do sistema (por exemplo, E_OUTOFMEMORY, E_ABORT, , E_UNEXPECTEDE_INVALIDARG, e assim por diante), é aceitável retornar o código de erro sem chamar explicitamente o SetErrorInfo método. Como estratégia de codificação defensiva, ao originar um erro HRESULT (incluindo erros do sistema), sempre chame o SetErrorInfo método, seja descrevendo ErrorInfo a falha com mais detalhes ou null.

  • Todas as funções que retornam um erro originado por outra chamada devem passar as informações que foram recebidas da chamada com falha no HRESULT sem modificar o ErrorInfo objeto.

Confira também