방법: HRESULT 및 예외 매핑How to: Map HRESULTs and Exceptions

COM 메서드는 HRESULT를 반환하여 오류를 보고하고, .NET 메서드는 예외를 throw하여 오류를 보고합니다.COM methods report errors by returning HRESULTs; .NET methods report them by throwing exceptions. 런타임은 두 항목 간의 전환을 처리합니다.The runtime handles the transition between the two. .NET Framework의 각 예외 클래스는 HRESULT에 매핑됩니다.Each exception class in the .NET Framework maps to an HRESULT.

사용자 정의 예외 클래스는 적절한 모든 HRESULT를 지정할 수 있습니다.User-defined exception classes can specify whatever HRESULT is appropriate. 이러한 예외 클래스는 예외 개체에서 HResult 필드를 설정하여 예외 생성 시 반환될 HRESULT를 동적으로 변경할 수 있습니다.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. 예외에 대한 추가 정보는 관리되지 않는 프로세스의 .NET 개체에서 구현되는 IErrorInfo 인터페이스를 통해 클라이언트에 제공됩니다.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.

System.Exception을 확장하는 클래스를 만들 경우 생성 중에 HRESULT 필드를 설정해야 합니다.If you create a class that extends System.Exception, you must set the HRESULT field during construction. 그러지 않으면 기본 클래스는 HRESULT 값을 할당합니다.Otherwise, the base class assigns the HRESULT value. 예외 생성자의 값을 제공하여 기존 HRESULT에 새 예외 클래스를 매핑할 수 있습니다.You can map new exception classes to an existing HRESULT by supplying the value in the exception's constructor.

스레드에 IErrorInfo가 있는 경우 런타임이 HRESULT를 무시할 수 있습니다.Note that the runtime will sometimes ignore an HRESULT in cases where there is an IErrorInfo present on the thread. HRESULTIErrorInfo가 동일한 오류를 나타내지 않을 경우 이 동작이 발생할 수 있습니다.This behavior can occur in cases where the HRESULT and the IErrorInfo do not represent the same error.

새 예외 클래스를 만들고 HRESULT에 매핑하려면To create a new exception class and map it to an HRESULT

  1. 다음 코드를 사용하여 NoAccessException이라는 새 예외 클래스를 만들고 HRESULT E_ACCESSDENIED에 매핑합니다.Use the following code 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. 예를 들어 다음 코드 예제의 사용자 지정 마샬러는 Marshal.ThrowExceptionForHR(int HResult) 메서드를 사용하여 특정 HRESULT 값이 포함된 예외를 throw합니다.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. 이 메서드는 HRESULT를 조회하고 해당하는 예외 형식을 생성합니다.The method looks up the HRESULT and generates the appropriate exception type. 예를 들어 다음 코드 조각의 HRESULT는 ArgumentException을 생성합니다.For example, the HRESULT in the following code fragment generates ArgumentException.

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

다음 표에서는 HRESULT와 .NET의 비교 가능한 예외 클래스 간의 일반적인 매핑을 제공합니다.The following table provides the common mappings from HRESULT to its comparable exception class in .NET. 명시적 매핑이 없는 HRESULT 값은 COMException에 매핑됩니다.HRESULT values without explicit mappings are mapped to COMException. 전체 최신 매핑은 dotnet/runtime 리포지토리에서 찾을 수 있습니다.The complete up-to-date mapping can be found in the dotnet/runtime repository.

HRESULTHRESULT .NET 예외.NET exception
COR_E_APPLICATION ApplicationException
COR_E_ARGUMENT 또는 E_INVALIDARGCOR_E_ARGUMENT or 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

확장된 오류 정보를 검색하려면 관리되는 클라이언트가 생성된 예외 개체의 필드를 검사해야 합니다.To retrieve extended error information, the managed client must examine the fields of the exception object that was generated. 예외 개체가 오류에 대한 유용한 정보를 제공하려면 COM 개체는 IErrorInfo 인터페이스를 구현해야 합니다.For the exception object to provide useful information about an error, the COM object must implement the IErrorInfo interface. 런타임은 IErrorInfo에서 제공된 정보를 사용하여 예외 개체를 초기화합니다.The runtime uses the information provided by IErrorInfo to initialize the exception object.

COM 개체가 IErrorInfo를 지원하지 않을 경우 런타임은 기본값으로 예외 개체를 초기화합니다.If the COM object does not support IErrorInfo, the runtime initializes an exception object with default values. 다음 표에서는 예외 개체와 연결된 각 필드를 나열하고 COM 개체가 IErrorInfo를 지원할 경우 기본 정보의 소스를 식별합니다.The following table lists each field associated with an exception object and identifies the source of default information when the COM object supports IErrorInfo.

스레드에 IErrorInfo가 있는 경우 런타임이 HRESULT를 무시할 수 있습니다.Note that the runtime will sometimes ignore an HRESULT in cases where there is an IErrorInfo present on the thread. HRESULTIErrorInfo가 동일한 오류를 나타내지 않을 경우 이 동작이 발생할 수 있습니다.This behavior can occur in cases where the HRESULT and the IErrorInfo do not represent the same error.

예외 필드Exception field COM의 정보 소스Source of Information from COM
ErrorCode 호출에서 반환된 HRESULT.HRESULT returned from call.
HelpLink IErrorInfo->HelpContext가 0이 아니면 IErrorInfo->GetHelpFile와 “#” 및 IErrorInfo->GetHelpContext를 연결하여 문자열을 구성합니다.If IErrorInfo->HelpContext is nonzero, the string is formed by concatenating IErrorInfo->GetHelpFile and "#" and IErrorInfo->GetHelpContext. 이외의 경우에는 IErrorInfo->GetHelpFile에서 문자열이 반환됩니다.Otherwise the string is returned from IErrorInfo->GetHelpFile.
InnerException 항상 null 참조(Visual Basic의 경우 Nothing).Always a null reference (Nothing in Visual Basic).
Message IErrorInfo->GetDescription에서 반환된 문자열.String returned from IErrorInfo->GetDescription.
Source IErrorInfo->GetSource에서 반환된 문자열.String returned from IErrorInfo->GetSource.
StackTrace 스택 추적입니다.The stack trace.
TargetSite 실패한 HRESULT를 반환한 메서드의 이름.The name of the method that returned the failing HRESULT.

Message, SourceStackTrace와 같은 예외 필드는 StackOverflowException에 사용할 수 없습니다.Exception fields, such as Message, Source, and StackTrace are not available for the StackOverflowException.

참조See also