Como fazer: Mapear HRESULTs e exceções

Os métodos COM reportam erros ao retornar HRESULTs; os métodos .NET reportam-nos através do lançamento de exceções. O runtime trata da transição entre os dois. Cada classe de exceção em .NET mapeia para um HRESULT.

As classes de exceção definidas pelo utilizador podem especificar qualquer HRESULT que seja apropriado. Estas classes de exceção podem alterar dinamicamente o HRESULT para ser devolvido quando a exceção é gerada, ao definir o HResult campo no objeto de exceção. Informação adicional sobre a exceção é fornecida ao cliente através da IErrorInfo interface, que é implementada no objeto .NET no processo não gerido.

Se criares uma classe que estende System.Exception, tens de definir o campo HRESULT durante a construção. Caso contrário, a classe base atribui o valor HRESULT. Pode mapear novas classes de exceção para um HRESULT existente fornecendo o valor no construtor da exceção.

Note que o ambiente de execução, por vezes, ignora um HRESULT nos casos em que existe um IErrorInfo presente no encadeamento. Este comportamento pode ocorrer nos casos em que os HRESULT e os IErrorInfo não representam o mesmo erro.

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

1. Use o código seguinte 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();
   }
   

Pode deparar-se com um programa (em qualquer linguagem de programação) que usa código gerido e não gerido ao mesmo tempo. Por exemplo, o empacotador personalizado no exemplo de código seguinte utiliza o método Marshal.ThrowExceptionForHR(int HResult) para gerar 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 seguinte fragmento de código gera ArgumentException.

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

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

Para obter informações detalhadas sobre o erro, o cliente gerido deve examinar os campos do objeto de exceção que foi gerado. Para que o objeto exceção forneça informação útil sobre um erro, o objeto COM deve implementar a IErrorInfo interface. O runtime utiliza a informação fornecida por IErrorInfo para inicializar o objeto de exceção.

Se o objeto COM não suportar IErrorInfo, o runtime inicializa um objeto exceção com valores predefinidos. A tabela seguinte lista cada campo associado a um objeto de exceção e identifica a origem das informações predefinidas quando o objeto COM suporta IErrorInfo.

Note que o ambiente de execução por vezes ignora um HRESULT quando existe um IErrorInfo presente na thread. Este comportamento pode ocorrer nos casos em que os HRESULT e os IErrorInfo não representam o mesmo erro.

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

Ver também

• Interoperabilidade COM avançada
• Exceções