COMException Class
TOC
Collapse the table of content
Expand the table of content

COMException Class

 

The exception that is thrown when an unrecognized HRESULT is returned from a COM method call.

Namespace:   System.Runtime.InteropServices
Assembly:  mscorlib (in mscorlib.dll)

System.Object
  System.Exception
    System.SystemException
      System.Runtime.InteropServices.ExternalException
        System.Runtime.InteropServices.COMException
          System.DirectoryServices.DirectoryServicesCOMException

[SerializableAttribute]
[ComVisibleAttribute(true)]
public class COMException : ExternalException

NameDescription
System_CAPS_pubmethodCOMException()

Initializes a new instance of the COMException class with default values.

System_CAPS_protmethodCOMException(SerializationInfo, StreamingContext)

Initializes a new instance of the COMException class from serialization data.

System_CAPS_pubmethodCOMException(String)

Initializes a new instance of the COMException class with a specified message.

System_CAPS_pubmethodCOMException(String, Exception)

Initializes a new instance of the COMException class with a specified error message and a reference to the inner exception that is the cause of this exception.

System_CAPS_pubmethodCOMException(String, Int32)

Initializes a new instance of the COMException class with a specified message and error code.

NameDescription
System_CAPS_pubpropertyData

Gets a collection of key/value pairs that provide additional user-defined information about the exception.(Inherited from Exception.)

System_CAPS_pubpropertyErrorCode

Gets the HRESULT of the error.(Inherited from ExternalException.)

System_CAPS_pubpropertyHelpLink

Gets or sets a link to the help file associated with this exception.(Inherited from Exception.)

System_CAPS_pubpropertyHResult

Gets or sets HRESULT, a coded numerical value that is assigned to a specific exception.(Inherited from Exception.)

System_CAPS_pubpropertyInnerException

Gets the Exception instance that caused the current exception.(Inherited from Exception.)

System_CAPS_pubpropertyMessage

Gets a message that describes the current exception.(Inherited from Exception.)

System_CAPS_pubpropertySource

Gets or sets the name of the application or the object that causes the error.(Inherited from Exception.)

System_CAPS_pubpropertyStackTrace

Gets a string representation of the immediate frames on the call stack.(Inherited from Exception.)

System_CAPS_pubpropertyTargetSite

Gets the method that throws the current exception.(Inherited from Exception.)

NameDescription
System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetBaseException()

When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions.(Inherited from Exception.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetObjectData(SerializationInfo, StreamingContext)

When overridden in a derived class, sets the SerializationInfo with information about the exception.(Inherited from Exception.)

System_CAPS_pubmethodGetType()

Gets the runtime type of the current instance.(Inherited from Exception.)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodToString()

Converts the contents of the exception to a string.(Overrides ExternalException.ToString().)

NameDescription
System_CAPS_proteventSerializeObjectState

Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception.(Inherited from Exception.)

The common language runtime transforms well-known HRESULTs to .NET Framework 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.

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.

Late-bound arguments and Microsoft Office objects

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, the .NET Framework 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.

Visual Studio and the hosting process

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.

Although you can use the COMException class to return specific HRESULTs to unmanaged clients, throwing a specific .NET Framework exception is better than using a generic exception. Consider that managed clients as well as unmanaged clients can use your .NET Framework object, and throwing an HRESULT to a managed caller is less comprehensible than throwing an exception.

Universal Windows Platform
Available since 4.5
.NET Framework
Available since 1.1
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show:
© 2016 Microsoft