Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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. The following example shows how to create a new exception class called NoAccessException and map it to the HRESULT E_ACCESSDENIED:

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 marshaler 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 complete mapping from each HRESULT to its comparable exception class in the .NET Framework.

HRESULT.NET exception
MSEE_E_APPDOMAINUNLOADEDAppDomainUnloadedException
COR_E_APPLICATIONApplicationException
COR_E_ARGUMENT or
E_INVALIDARG
ArgumentException
COR_E_ARGUMENTOUTOFRANGEArgumentOutOfRangeException
COR_E_ARITHMETIC or
ERROR_ARITHMETIC_OVERFLOW
ArithmeticException
COR_E_ARRAYTYPEMISMATCHArrayTypeMismatchException
COR_E_BADIMAGEFORMAT or ERROR_BAD_FORMATBadImageFormatException
COR_E_COMEMULATE_ERRORCOMEmulateException
COR_E_CONTEXTMARSHALContextMarshalException
COR_E_CORECoreException
NTE_FAILCryptographicException
COR_E_DIRECTORYNOTFOUND or
ERROR_PATH_NOT_FOUND
DirectoryNotFoundException
COR_E_DIVIDEBYZERODivideByZeroException
COR_E_DUPLICATEWAITOBJECTDuplicateWaitObjectException
COR_E_ENDOFSTREAMEndOfStreamException
COR_E_TYPELOADEntryPointNotFoundException
COR_E_EXCEPTIONException
COR_E_EXECUTIONENGINEExecutionEngineException
COR_E_FIELDACCESSFieldAccessException
COR_E_FILENOTFOUND or
ERROR_FILE_NOT_FOUND
FileNotFoundException
COR_E_FORMATFormatException
COR_E_INDEXOUTOFRANGEIndexOutOfRangeException
COR_E_INVALIDCAST or
E_NOINTERFACE
InvalidCastException
COR_E_INVALIDCOMOBJECTInvalidComObjectException
COR_E_INVALIDFILTERCRITERIAInvalidFilterCriteriaException
COR_E_INVALIDOLEVARIANTTYPEInvalidOleVariantTypeException
COR_E_INVALIDOPERATIONInvalidOperationException
COR_E_IOIOException
COR_E_MEMBERACCESSAccessException
COR_E_METHODACCESSMethodAccessException
COR_E_MISSINGFIELDMissingFieldException
COR_E_MISSINGMANIFESTRESOURCEMissingManifestResourceException
COR_E_MISSINGMEMBERMissingMemberException
COR_E_MISSINGMETHODMissingMethodException
COR_E_MULTICASTNOTSUPPORTEDMulticastNotSupportedException
COR_E_NOTFINITENUMBERNotFiniteNumberException
E_NOTIMPLNotImplementedException
COR_E_NOTSUPPORTEDNotSupportedException
COR_E_NULLREFERENCE or
E_POINTER
NullReferenceException
COR_E_OUTOFMEMORY or

E_OUTOFMEMORY

OutOfMemoryException
COR_E_OVERFLOWOverflowException
COR_E_PATHTOOLONG or
ERROR_FILENAME_EXCED_RANGE
PathTooLongException
COR_E_RANKRankException
COR_E_REFLECTIONTYPELOADReflectionTypeLoadException
COR_E_REMOTINGRemotingException
COR_E_SAFEARRAYTYPEMISMATCHSafeArrayTypeMismatchException
COR_E_SECURITYSecurityException
COR_E_SERIALIZATIONSerializationException
COR_E_STACKOVERFLOW or
ERROR_STACK_OVERFLOW
StackOverflowException
COR_E_SYNCHRONIZATIONLOCKSynchronizationLockException
COR_E_SYSTEMSystemException
COR_E_TARGETTargetException
COR_E_TARGETINVOCATIONTargetInvocationException
COR_E_TARGETPARAMCOUNTTargetParameterCountException
COR_E_THREADABORTEDThreadAbortException
COR_E_THREADINTERRUPTEDThreadInterruptedException
COR_E_THREADSTATEThreadStateException
COR_E_THREADSTOPThreadStopException
COR_E_TYPELOADTypeLoadException
COR_E_TYPEINITIALIZATIONTypeInitializationException
COR_E_VERIFICATIONVerificationException
COR_E_WEAKREFERENCEWeakReferenceException
COR_E_VTABLECALLSNOTSUPPORTEDVTableCallsNotSupportedException
All other HRESULTsCOMException

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.

Exception fieldSource of Information from COM
ErrorCodeHRESULT returned from call.
HelpLinkIf IErrorInfo->HelpContext is nonzero, the string is formed by concatenating IErrorInfo->GetHelpFile and "#" and IErrorInfo->GetHelpContext. Otherwise the string is returned from IErrorInfo->GetHelpFile.
InnerExceptionAlways a null reference (Nothing in Visual Basic).
MessageString returned from IErrorInfo->GetDescription.
SourceString returned from IErrorInfo->GetSource.
StackTraceThe stack trace.
TargetSite The name of the method that returned the failing HRESULT.

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

See Also

Advanced COM Interop | Handling and Throwing Exceptions

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2015 Microsoft