共用方式為


HOW TO:對應 HRESULT 和例外狀況

更新:2007 年 11 月

COM 方法是藉由傳回 HRESULT 來報告錯誤;.NET 方法則是藉由擲回例外狀況來報告錯誤。Runtime 則負責處理兩者之間的轉換。.NET Framework 的每一個例外狀況類別都會對應到一個 HRESULT。

使用者定義的例外狀況類別可以指定任何適當的 HRESULT。當例外狀況是藉由設定例外狀況物件上的 HResult 欄位而產生時,這些例外狀況類別可以動態地變更要傳回的 HRESULT。有關例外狀況的其他資訊,會透過實作於 Unmanaged 處理序中 .NET 物件上的 IErrorInfo 介面提供給用戶端。

如果您建立擴充 System.Exception 的類別,您必須在建構期間設定 HRESULT 欄位。否則,基底類別會指派 HRESULT 值。您可以在例外狀況的建構函式 (Constructor) 中提供值,將新的例外狀況類別對應到現有的 HRESULT。

請注意,執行階段有時候會忽略 HRESULT,以應付萬一執行緒上存在 IErrorInfo 的情況。萬一 HRESULT 和 IErrorInfo 並不表示相同的錯誤,就可能會發生這個行為。

若要建立新 Exception 類別並對應至 HRESULT

  • 使用下列程式碼建立名稱為 NoAccessException 的新 Exception 類別,並對應至 HRESULT E_ACCESSDENIED。

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

您或許會碰到同時使用 Managed 和 Unmanaged 程式碼的程式 (以任何程式語言所撰寫)。例如,下列程式碼範例中的自訂封送處理器是使用 Marshal.ThrowExceptionForHR(int HResult) 方法來擲回具有特定 HRESULT 值的例外狀況。這個方法會查詢 HRESULT 並且產生適當的例外狀況型別。例如,下列程式碼片段中的 HRESULT 會產生 ArgumentException

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

以下表格提供從每一個 HRESULT 到它在 .NET Framework 中相當的例外狀況類別的完整對應。

HRESULT

.NET 例外狀況

MSEE_E_APPDOMAINUNLOADED

AppDomainUnloadedException

COR_E_APPLICATION

ApplicationException

COR_E_ARGUMENT 或 E_INVALIDARG

ArgumentException

COR_E_ARGUMENTOUTOFRANGE

ArgumentOutOfRangeException

COR_E_ARITHMETIC 或 ERROR_ARITHMETIC_OVERFLOW

ArithmeticException

COR_E_ARRAYTYPEMISMATCH

ArrayTypeMismatchException

COR_E_BADIMAGEFORMAT 或 ERROR_BAD_FORMAT

BadImageFormatException

COR_E_COMEMULATE_ERROR

COMEmulateException

COR_E_CONTEXTMARSHAL

ContextMarshalException

COR_E_CORE

CoreException

NTE_FAIL

CryptographicException

COR_E_DIRECTORYNOTFOUND 或 ERROR_PATH_NOT_FOUND

DirectoryNotFoundException

COR_E_DIVIDEBYZERO

DivideByZeroException

COR_E_DUPLICATEWAITOBJECT

DuplicateWaitObjectException

COR_E_ENDOFSTREAM

EndOfStreamException

COR_E_TYPELOAD

EntryPointNotFoundException

COR_E_EXCEPTION

Exception

COR_E_EXECUTIONENGINE

ExecutionEngineException

COR_E_FIELDACCESS

FieldAccessException

COR_E_FILENOTFOUND 或 ERROR_FILE_NOT_FOUND

FileNotFoundException

COR_E_FORMAT

FormatException

COR_E_INDEXOUTOFRANGE

IndexOutOfRangeException

COR_E_INVALIDCAST 或 E_NOINTERFACE

InvalidCastException

COR_E_INVALIDCOMOBJECT

InvalidComObjectException

COR_E_INVALIDFILTERCRITERIA

InvalidFilterCriteriaException

COR_E_INVALIDOLEVARIANTTYPE

InvalidOleVariantTypeException

COR_E_INVALIDOPERATION

InvalidOperationException

COR_E_IO

IOException

COR_E_MEMBERACCESS

AccessException

COR_E_METHODACCESS

MethodAccessException

COR_E_MISSINGFIELD

MissingFieldException

COR_E_MISSINGMANIFESTRESOURCE

MissingManifestResourceException

COR_E_MISSINGMEMBER

MissingMemberException

COR_E_MISSINGMETHOD

MissingMethodException

COR_E_MULTICASTNOTSUPPORTED

MulticastNotSupportedException

COR_E_NOTFINITENUMBER

NotFiniteNumberException

E_NOTIMPL

NotImplementedException

COR_E_NOTSUPPORTED

NotSupportedException

COR_E_NULLREFERENCE 或 E_POINTER

NullReferenceException

COR_E_OUTOFMEMORY 或

E_OUTOFMEMORY

OutOfMemoryException

COR_E_OVERFLOW

OverflowException

COR_E_PATHTOOLONG 或 ERROR_FILENAME_EXCED_RANGE

PathTooLongException

COR_E_RANK

RankException

COR_E_REFLECTIONTYPELOAD

ReflectionTypeLoadException

COR_E_REMOTING

RemotingException

COR_E_SAFEARRAYTYPEMISMATCH

SafeArrayTypeMismatchException

COR_E_SECURITY

SecurityException

COR_E_SERIALIZATION

SerializationException

COR_E_STACKOVERFLOW 或 ERROR_STACK_OVERFLOW

StackOverflowException

COR_E_SYNCHRONIZATIONLOCK

SynchronizationLockException

COR_E_SYSTEM

SystemException

COR_E_TARGET

TargetException

COR_E_TARGETINVOCATION

TargetInvocationException

COR_E_TARGETPARAMCOUNT

TargetParameterCountException

COR_E_THREADABORTED

ThreadAbortException

COR_E_THREADINTERRUPTED

ThreadInterruptedException

COR_E_THREADSTATE

ThreadStateException

COR_E_THREADSTOP

ThreadStopException

COR_E_TYPELOAD

TypeLoadException

COR_E_TYPEINITIALIZATION

TypeInitializationException

COR_E_VERIFICATION

VerificationException

COR_E_WEAKREFERENCE

WeakReferenceException

COR_E_VTABLECALLSNOTSUPPORTED

VTableCallsNotSupportedException

所有其他 HRESULT

COMException

若要擷取擴充錯誤資訊,Managed 用戶端必須檢查所產生之例外狀況物件的欄位。若要讓例外狀況物件提供有關錯誤的有用資訊,COM 物件必須實作 IErrorInfo 介面。Runtime 會使用 IErrorInfo 提供的資訊來初始化例外狀況物件。

如果 COM 物件不支援 IErrorInfo,Runtime 會使用預設值來初始化例外狀況物件。以下表格列出與例外狀況物件關聯的每一個欄位,並且指出當 COM 物件支援 IErrorInfo 時的預設資訊來源。

請注意,執行階段有時候會忽略 HRESULT,以應付萬一執行緒上存在 IErrorInfo 的情況。萬一 HRESULT 和 IErrorInfo 並不表示相同的錯誤,就可能會發生這個行為。

例外狀況欄位

來自 COM 的資訊來源

ErrorCode

從呼叫傳回的 HRESULT。

HelpLink

如果 IErrorInfo->HelpContext 為非零值 (Nonzero),則字串是由連結 IErrorInfo->GetHelpFile、「#」和 IErrorInfo->GetHelpContext 所構成。否則,字串是由 IErrorInfo->GetHelpFile 所傳回。

InnerException

一定是 Null 參考 (在 Visual Basic 中為 Nothing)。

Message

IErrorInfo->GetDescription 傳回的字串。

Source

IErrorInfo->GetSource 傳回的字串。

StackTrace

堆疊追蹤。

TargetSite

傳回失敗 HRESULT 之方法的名稱。

MessageSourceStackTrace 這些例外狀況欄位,並不適用於 StackOverflowException

請參閱

其他資源

進階 COM 互通性

處理和擲回例外狀況