Como: Mapear HRESULTs e exceções

Os métodos COM relatam erros retornando HRESULTs; os métodos .NET os relatam lançando exceções. O tempo de execução lida com a transição entre os dois. Cada classe de exceção no .NET Framework 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 que se estende, System.Exceptionvocê deve definir o campo HRESULT durante a construção. Caso contrário, a classe base atribui 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 tempo de execução às vezes ignora um HRESULT nos casos em que há um IErrorInfo presente no thread. Esse comportamento pode ocorrer nos 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 lançar uma exceção com um valor HRESULT específico. O método procura 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 no .NET. Os valores HRESULT sem mapeamentos explícitos são mapeados para COMException. O mapeamento completo 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 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 inicializa 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 tempo de execução às vezes ignora um HRESULT nos casos em que há um IErrorInfo presente no thread. Esse comportamento pode ocorrer nos 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 o StackOverflowException.

Consulte também

• Interoperabilidade COM avançada
• Exceções