Como: Mapear HRESULTs e exceções

Métodos COM relatam erros retornando HRESULTs; métodos .NET os relatam gerando exceções. O runtime manipula a transição entre os dois. Cada classe de exceção do .NET Framework mapeia para um HRESULT.

Classes de exceção definidas pelo usuário podem especificar qualquer HRESULT apropriado. Essas classes de exceção podem alterar dinamicamente o HRESULT a ser retornado quando a exceção é gerada definindo o campo HResult no objeto de exceção. Informações adicionais sobre a exceção são fornecidas ao cliente por meio da interface IErrorInfo, que é implementada no objeto .NET no processo não gerenciado.

Se você criar uma classe que estenda System.Exception, deverá definir o campo HRESULT durante a construção. Caso contrário, a classe base atribui o valor de HRESULT. Você pode mapear as novas classes de exceção para um HRESULT existente, fornecendo o valor no construtor da exceção.

Observe que o runtime, às vezes, ignorará um HRESULT em casos nos quais um IErrorInfo estiver presente no thread. Esse comportamento poderá ocorrer nos casos em que o HRESULT e o IErrorInfo não representarem o mesmo erro.

Para criar uma nova classe de exceção e mapeá-la para um HRESULT

1. Use o código a seguir para criar uma nova classe de exceção chamada NoAccessException e mapeá-la para o HRESULT E_ACCESSDENIED.

   Class NoAccessException : public ApplicationException
   {
       NoAccessException () {
       HResult = E_ACCESSDENIED;
   }
   }
   CMyClass::MethodThatThrows
   {
   throw new NoAccessException();
   }
   

Você pode encontrar um programa (em qualquer linguagem de programação) que usa o código gerenciado e não gerenciado simultaneamente. Por exemplo, o marshaller personalizado no exemplo de código a seguir usa o método Marshal.ThrowExceptionForHR(int HResult) para lançar uma exceção com um valor HRESULT específico. O método pesquisa o HRESULT e gera o tipo de exceção apropriado. Por exemplo, o HRESULT no fragmento de código a seguir gera ArgumentException.

CMyClass::MethodThatThrows
{
    Marshal.ThrowExceptionForHR(COR_E_ARGUMENT);
}

A tabela a seguir fornece os mapeamentos comuns do HRESULT para sua classe de exceção comparável no .NET. Os valores HRESULT sem mapeamentos explícitos são mapeados para COMException. O mapeamento completo e atualizado pode ser encontrado no repositório dotnet/runtime.

Para recuperar informações sobre erros estendidos, o cliente gerenciado deve examinar os campos do objeto de exceção gerado. Para que o objeto de exceção forneça informações úteis sobre um erro, o objeto COM deve implementar a interface IErrorInfo. O tempo de execução usa as informações fornecidas por IErrorInfo para inicializar o objeto de exceção.

Se o objeto COM não oferecer suporte a IErrorInfo, o tempo de execução inicializará um objeto de exceção com valores padrão. A tabela a seguir lista cada campo associado a um objeto de exceção e identifica a fonte de informações padrão quando o objeto COM oferece suporte a IErrorInfo.

Observe que o runtime, às vezes, ignorará um HRESULT em casos nos quais um IErrorInfo estiver presente no thread. Esse comportamento poderá ocorrer nos casos em que o HRESULT e o IErrorInfo não representarem o mesmo erro.

Campos de exceção, como Message, Source e StackTrace não estão disponíveis para o StackOverflowException.

Confira também

• Interoperabilidade COM avançada
• Exceções