Appendix C. HRESULT to .NET Exception Transformations

When a COM member (or PInvoke signature marked with PreserveSig=false) returns a failure HRESULT, a .NET exception is thrown. The type of the exception depends on the HRESULT value, according to the tables in this appendix. The exceptions listed are the only ones that can be directly thrown by the CLR in response to a COM object returning a failure HRESULT, and are a subset of the exceptions defined in the mscorlib assembly. The only reason that the list doesn’t include all exceptions defined in mscorlib is that a handful of exceptions share the same HRESULT values, so one exception type must be chosen when the shared value is returned from COM.

Table C.1 lists exception types alphabetically (excluding the namespace), to answer the question, “What HRESULT caused this exception to be thrown?” for an author of a .NET component using COM. This information can be obtained programmatically by calling System.Runtime.InteropServices.Marshal.GetHRForException, although for exceptions that can be caused by multiple HRESULTs, only one HRESULT (the one listed in bold in the table) is returned.

Table C.1. Exception Types Listed Alphabetically

Table C.2 contains the same information as Table C.1, but lists the HRESULTs numerically, to answer a COM component author’s question, “If I return this HRESULT, what exception will a .NET client see thrown?” This information can be obtained by calling the System.Runtime.InteropServices.Marshal.ThrowExceptionForHR method, but this involves catching the thrown exception to discover its type.

Table C.2. Exception Types Listed Numerically by HRESULT Value

Here are a few notes about the tables:

• For some exceptions, multiple HRESULT values cause the same exception to be thrown. The bold HRESULTs in Table C.1 represent the default values that correspond to the exception when it’s thrown from .NET to COM (shown in Appendix D).

• Any listed names beginning with ERROR are Win32 error codes that must be added to 0x80070000 to get the listed HRESULT values with FACILITY_WIN32.

• A few HRESULTs have multiple names, because some .NET HRESULTs (beginning with COR) are defined with the same value as classic COM HRESULTs. A list of named .NET HRESULTs can be found in CorError.h.

• Any returned HRESULTs not listed in these tables result in a System.Runtime.InteropServices.COMException being thrown.