System.Runtime.InteropServices.COMException class
This article provides supplementary remarks to the reference documentation for this API.
The COMException class is the exception that's thrown when an unrecognized HRESULT is returned from a COM method call.
The common language runtime transforms well-known HRESULTs to .NET exceptions, enabling COM objects to return meaningful error information to managed clients. The HRESULT-to-exception mapping also works in the other direction by returning specific HRESULTs to unmanaged clients. For mapping details, see How to map HRESULTs and exceptions.
When the runtime encounters an unfamiliar HRESULT (an HRESULT that lacks a specific, corresponding exception), it throws an instance of the COMException class. This all-purpose exception exposes the same members as any exception, and inherits a public ErrorCode property that contains the HRESULT returned by the callee. If an error message is available to the runtime (obtained from the IErrorInfo interface or the Err object in Visual Basic, or in some cases from the operating system), the message is returned to the caller. However, if the COM component developer fails to include an error message, the runtime returns the eight-digit HRESULT in place of a message string. Having an HRESULT allows the caller to determine the cause of the generic exception.
Handle a COMException exception
The following are some considerations for troubleshooting a COMException exception.
Check the ErrorCode property When the runtime encounters an unfamiliar HRESULT and throws a COMException exception, the ErrorCode property includes either the error message or, if an error message is unavailable, the eight-digit HRESULT value. The error message or the HRESULT value can help you determine the cause of the exception.
For a list of HRESULT values, see Common HRESULT Values.
When passing late-bound arguments to methods of Microsoft Office objects, a COMException exception may be thrown when the objects are COM objects. The late binder assumes that such method calls involve a ByRef parameter and that the property you pass has a set accessor. If the property does not, .NET generates a MissingMethodException exception (with a CORE_E_MISSINGMETHOD HRESULT ). To work around this behavior, use early-bound objects or pass a variable instead of a property of the object.
COM is used to communicate between Visual Studio and the hosting process. Because it is used before code runs, a call to CoInitializeSecurity causes this exception to be thrown. In some cases, running Visual Studio as Administrator may resolve the issue. You can also disable the hosting process.
Throw a COMException exception
Although you can use the COMException class to return specific HRESULTs to unmanaged clients, throwing a specific .NET exception is better than using a generic exception. Consider that managed clients as well as unmanaged clients can use your .NET object, and throwing an HRESULT to a managed caller is less comprehensible than throwing an exception.
