How to: Map HRESULTs and Exceptions

COM methods report errors by returning HRESULTs; .NET methods report them by throwing exceptions. The runtime handles the transition between the two. Each exception class in the .NET Framework maps to an HRESULT.

User-defined exception classes can specify whatever HRESULT is appropriate. These exception classes can dynamically change the HRESULT to be returned when the exception is generated by setting the HResult field on the exception object. Additional information about the exception is provided to the client through the IErrorInfo interface, which is implemented on the .NET object in the unmanaged process.

If you create a class that extends System.Exception, you must set the HRESULT field during construction. Otherwise, the base class assigns the HRESULT value. You can map new exception classes to an existing HRESULT by supplying the value in the exception's constructor.

Note that the runtime will sometimes ignore an HRESULT in cases where there is an IErrorInfo present on the thread. This behavior can occur in cases where the HRESULT and the IErrorInfo do not represent the same error.

1. Use the following code to create a new exception class called NoAccessException and map it to the HRESULT E_ACCESSDENIED.

   C++ Copy

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

You might encounter a program (in any programming language) that uses both managed and unmanaged code at the same time. For example, the custom marshaller in the following code example uses the Marshal.ThrowExceptionForHR(int HResult) method to throw an exception with a specific HRESULT value. The method looks up the HRESULT and generates the appropriate exception type. For example, the HRESULT in the following code fragment generates ArgumentException.

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

The following table provides the common mappings from HRESULT to its comparable exception class in .NET. HRESULT values without explicit mappings are mapped to COMException. The complete up-to-date mapping can be found in the dotnet/runtime repository.

To retrieve extended error information, the managed client must examine the fields of the exception object that was generated. For the exception object to provide useful information about an error, the COM object must implement the IErrorInfo interface. The runtime uses the information provided by IErrorInfo to initialize the exception object.

If the COM object does not support IErrorInfo, the runtime initializes an exception object with default values. The following table lists each field associated with an exception object and identifies the source of default information when the COM object supports IErrorInfo.

Note that the runtime will sometimes ignore an HRESULT in cases where there is an IErrorInfo present on the thread. This behavior can occur in cases where the HRESULT and the IErrorInfo do not represent the same error.

Exception fields, such as Message, Source, and StackTrace are not available for the StackOverflowException.

• Advanced COM Interoperability
• Exceptions