Classe System.Runtime.InteropServices.COMException

Este artigo fornece comentários complementares à documentação de referência para esta API.

A classe COMException é a exceção que é lançada quando um HRESULT não reconhecido é retornado de uma chamada de método COM.

O CLR (Common Language Runtime) transforma HRESULTs conhecidos em exceções .NET, permitindo que os objetos COM retornem informações de erro significativas aos clientes gerenciados. O mapeamento de HRESULT para exceção também funciona na outra direção, retornando HRESULTs específicas para clientes não gerenciados. Para obter detalhes de mapeamento, consulte Como mapear HRESULTs e exceções.

Quando o runtime encontra um HRESULT desconhecido (um HRESULT que não tem uma exceção específica e correspondente), ele gera uma instância da COMException classe. Esta exceção de uso geral expõe os mesmos membros que qualquer exceção e herda uma propriedade pública ErrorCode que contém o HRESULT retornado pelo chamador. Se uma mensagem de erro estiver disponível para o runtime (obtida da interface IErrorInfo ou do Err objeto no Visual Basic ou em alguns casos do sistema operacional), a mensagem será retornada ao chamador. No entanto, se o desenvolvedor do componente COM não incluir uma mensagem de erro, o runtime retornará o HRESULT de oito dígitos no lugar de uma cadeia de caracteres de mensagem. Ter um HRESULT permite que o chamador determine a causa da exceção genérica.

Manipular uma exceção COMException

Veja a seguir algumas considerações para solucionar problemas de uma COMException exceção.

Verifique a propriedade ErrorCode. Quando o runtime encontra um HRESULT desconhecido e gera uma exceção COMException, a propriedade ErrorCode inclui a mensagem de erro ou, se uma mensagem de erro não estiver disponível, o valor HRESULT de oito dígitos. A mensagem de erro ou o valor HRESULT podem ajudá-lo a determinar a causa da exceção.

Para obter uma lista de valores HRESULT, consulte Valores HRESULT Comuns.

Ao passar argumentos com limite tardio para métodos de objetos do Microsoft Office, uma COMException exceção pode ser gerada quando os objetos são objetos COM. A associação tardia presume que essas chamadas de método envolvem um parâmetro ByRef e que a propriedade passada por você tem um acessador set. Se a propriedade não fizer isso, .NET gerará uma MissingMethodException exceção (com um CORE_E_MISSINGMETHOD HRESULT). Para contornar esse comportamento, use objetos associados antecipadamente ou passe uma variável em vez de uma propriedade do objeto.

O COM é usado para se comunicar entre o Visual Studio e o processo de hospedagem. Como ele é usado antes da execução do código, uma chamada para CoInitializeSecurity faz com que essa exceção seja gerada. Em alguns casos, executar o Visual Studio como Administrador pode resolver o problema. Você também pode desabilitar o processo de hospedagem.

Gerar uma exceção COMException

Embora você possa usar a COMException classe para retornar HRESULTs específicos para clientes não gerenciados, gerar uma exceção específica do .NET é melhor do que usar uma exceção genérica. Considere que clientes gerenciados, bem como clientes não gerenciados, podem usar seu objeto .NET e lançar um HRESULT para um chamador gerenciado é menos compreensível do que gerar uma exceção.