Como mapear HRESULTs e exceções

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

As 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 HResult campo no objeto de exceção. Informações adicionais sobre a exceção são fornecidas ao cliente por meio da IErrorInfo interface, que é implementada no objeto .NET no processo não gerenciado.

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

Observe que o runtime às vezes ignora um HRESULT nos casos em que há um IErrorInfo presente na thread. Esse comportamento pode ocorrer em casos em que o HRESULT e o IErrorInfo não representam 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 código gerenciado e não gerenciado ao mesmo tempo. Por exemplo, o marshaller personalizado no exemplo de código a seguir usa o Marshal.ThrowExceptionForHR(int HResult) método para gerar 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 de HRESULT para sua classe de exceção comparável em .NET. 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 de erro estendidas, o cliente gerenciado deve examinar os campos do objeto de exceção que foi gerado. Para que o objeto de exceção forneça informações úteis sobre um erro, o objeto COM deve implementar a IErrorInfo interface. O runtime usa as informações fornecidas IErrorInfo para inicializar o objeto de exceção.

Se o objeto COM não der suporte IErrorInfo, o runtime 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 origem das informações padrão quando o objeto COM é compatível IErrorInfo.

Observe que o runtime às vezes ignorará um HRESULT nos casos em que houver um IErrorInfo presente na thread. Esse comportamento pode ocorrer em casos em que o HRESULT e o IErrorInfo não representam o mesmo erro.

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

Consulte também

• Interoperabilidade Avançada COM
• Exceções