Cara: Memetakan HRESULT dan pengecualian

Metode COM melaporkan kesalahan dengan mengembalikan HRESULTs; .NET metode melaporkannya dengan melemparkan pengecualian. Runtime mengelola transisi antara keduanya. Setiap kelas pengecualian di .NET dipetakan ke sebuah HRESULT.

Kelas pengecualian yang ditentukan pengguna dapat menentukan HRESULT apa pun yang sesuai. Kelas pengecualian ini dapat secara dinamis mengubah HRESULT untuk dikembalikan ketika pengecualian dihasilkan dengan mengatur HResult bidang pada objek pengecualian. Informasi tambahan tentang pengecualian diberikan kepada klien melalui IErrorInfo antarmuka, yang diimplementasikan pada objek .NET dalam proses yang tidak dikelola.

Jika Anda membuat kelas yang diperluas System.Exception, Anda harus mengatur bidang HRESULT selama konstruksi. Jika tidak, kelas dasar menetapkan nilai HRESULT. Anda dapat memetakan kelas pengecualian baru ke HRESULT yang ada dengan menyediakan nilai dalam konstruktor pengecualian.

Perhatikan bahwa runtime terkadang akan mengabaikan HRESULT jika IErrorInfo ada pada thread. Perilaku ini dapat terjadi dalam kasus di mana HRESULT dan IErrorInfo tidak mewakili kesalahan yang sama.

Untuk membuat kelas pengecualian baru dan memetakannya ke HRESULT

1. Gunakan kode berikut untuk membuat kelas pengecualian baru yang disebut NoAccessException dan memetakannya ke HRESULT E_ACCESSDENIED.

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

Anda mungkin menemukan program (dalam bahasa pemrograman apa pun) yang menggunakan kode terkelola dan tidak terkelola secara bersamaan. Misalnya, marshaller kustom dalam contoh kode berikut menggunakan metode Marshal.ThrowExceptionForHR(int HResult) untuk memunculkan pengecualian dengan nilai HRESULT tertentu. Metode mencari HRESULT dan menghasilkan jenis pengecualian yang sesuai. Misalnya, HRESULT dalam fragmen kode berikut menghasilkan ArgumentException.

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

Tabel berikut ini menyediakan pemetaan umum dari HRESULT ke kelas pengecualian yang sebanding di .NET. Nilai HRESULT tanpa pemetaan eksplisit dipetakan ke COMException. Pemetaan lengkap dan terkini dapat ditemukan di repositori dotnet/runtime.

HRESULT	pengecualian .NET
COR_E_APPLICATION	ApplicationException
COR_E_ARGUMENT atau E_INVALIDARG	ArgumentException
COR_E_ARGUMENTOUTOFRANGE	ArgumentOutOfRangeException
COR_E_ARITHMETIC or ERROR_ARITHMETIC_OVERFLOW	ArithmeticException
COR_E_ARRAYTYPEMISMATCH	ArrayTypeMismatchException
COR_E_BADIMAGEFORMAT or ERROR_BAD_FORMAT	BadImageFormatException
COR_E_DIRECTORYNOTFOUND or ERROR_PATH_NOT_FOUND	DirectoryNotFoundException
COR_E_DIVIDEBYZERO	DivideByZeroException
COR_E_DUPLICATEWAITOBJECT	DuplicateWaitObjectException
COR_E_ENDOFSTREAM	EndOfStreamException
COR_E_ENTRYPOINTNOTFOUND	EntryPointNotFoundException
COR_E_EXCEPTION	Exception
COR_E_EXECUTIONENGINE	ExecutionEngineException
COR_E_FIELDACCESS	FieldAccessException
COR_E_FILENOTFOUND or ERROR_FILE_NOT_FOUND	FileNotFoundException
COR_E_FORMAT	FormatException
COR_E_INDEXOUTOFRANGE	IndexOutOfRangeException
COR_E_INVALIDCAST or E_NOINTERFACE	InvalidCastException
COR_E_INVALIDFILTERCRITERIA	InvalidFilterCriteriaException
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_NOTFINITENUMBER	NotFiniteNumberException
E_NOTIMPL	NotImplementedException
COR_E_NOTSUPPORTED	NotSupportedException
COR_E_NULLREFERENCE orE_POINTER	NullReferenceException
COR_E_OUTOFMEMORY or E_OUTOFMEMORY	OutOfMemoryException
COR_E_OVERFLOW	OverflowException
COR_E_PATHTOOLONG or ERROR_FILENAME_EXCED_RANGE	PathTooLongException
COR_E_RANK	RankException
COR_E_REFLECTIONTYPELOAD	ReflectionTypeLoadException
COR_E_SECURITY	SecurityException
COR_E_SERIALIZATION	SerializationException
COR_E_STACKOVERFLOW orERROR_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_THREADINTERRUPTED	ThreadInterruptedException
COR_E_THREADSTATE	ThreadStateException
COR_E_TYPELOAD	TypeLoadException
COR_E_TYPEINITIALIZATION	TypeInitializationException
COR_E_VERIFICATION	VerificationException

Untuk mengambil informasi kesalahan yang diperluas, klien terkelola harus memeriksa bidang objek pengecualian yang dihasilkan. Agar objek pengecualian memberikan informasi yang berguna tentang kesalahan, objek COM harus mengimplementasikan IErrorInfo antarmuka. Runtime menggunakan informasi yang disediakan oleh IErrorInfo untuk menginisialisasi objek pengecualian.

Jika objek COM tidak mendukung IErrorInfo, runtime menginisialisasi objek pengecualian dengan nilai default. Tabel berikut mencantumkan setiap bidang yang terkait dengan objek pengecualian dan mengidentifikasi sumber informasi default saat objek COM mendukung IErrorInfo.

Perhatikan bahwa runtime terkadang mengabaikan HRESULT dalam kasus ketika IErrorInfo ada pada thread. Perilaku ini dapat terjadi dalam kasus di mana HRESULT dan IErrorInfo tidak mewakili kesalahan yang sama.

Bidang pengecualian	Sumber Informasi dari COM
ErrorCode	HRESULT kembali dari panggilan.
HelpLink	Jika IErrorInfo->HelpContext bukan nol, string dibentuk dengan menggabungkan IErrorInfo->GetHelpFile dan "#" dan IErrorInfo->GetHelpContext. Jika tidak, string dikembalikan dari IErrorInfo->GetHelpFile.
InnerException	Selalu referensi null (Nothing dalam Visual Basic).
Message	String yang dikembalikan dari IErrorInfo->GetDescription.
Source	String yang dikembalikan dari IErrorInfo->GetSource.
StackTrace	Jejak tumpukan.
TargetSite	Nama metode yang mengembalikan HRESULT yang gagal.

Bidang pengecualian, seperti Message, , dan Source tidak tersedia untuk StackTraceStackOverflowException.

Baca juga

• Interoperabilitas COM Tingkat Lanjut
• Pengecualian