Практическое руководство. Сопоставление значений HRESULT и исключений

Статья
11/28/2022
Чтение занимает 2 мин

Методы COM сообщают об ошибках, возвращая значения HRESULT. Методы .NET в этом случае вызывают исключения. Среда выполнения обеспечивает сопоставление этих двух элементов. Каждый класс платформы .NET Framework сопоставляется со значением HRESULT.

Соответствующие значения HRESULT задаются определяемыми пользователем классами исключений. Эти классы исключений могут динамически изменять значение HRESULT, возвращаемое при возникновении исключения, устанавливая поле HResult соответствующего объекта исключения. Дополнительные сведения об исключении предоставляются клиенту посредством интерфейса IErrorInfo, который реализуется для объекта .NET в неуправляемом процессе.

При создании класса, который расширяет System.Exception, необходимо устанавливать значение поля HRESULT во время построения. В противном случае значение HRESULT будет присваиваться базовым классом. Чтобы сопоставить новые классы исключений с существующим значением HRESULT, укажите значение в конструкторе исключения.

Обратите внимание, что среда выполнения в некоторых случаях будет игнорировать значение HRESULT, если в потоке присутствует IErrorInfo. Это возможно в тех случаях, когда HRESULT и IErrorInfo представляют разные ошибки.

Создание нового класса исключения и его сопоставление со значением HRESULT

В следующем коде создается новый класс исключения NoAccessException, который сопоставляется со значением HRESULT E_ACCESSDENIED.
```
Class NoAccessException : public ApplicationException
{
    NoAccessException () {
    HResult = E_ACCESSDENIED;
}
}
CMyClass::MethodThatThrows
{
throw new NoAccessException();
}
```

На любом языке программирования могут встречаться программы, в которых одновременно используется управляемый и неуправляемый код. Например, Пользовательский метод упаковки в следующем примере кода используется Marshal.ThrowExceptionForHR(int HResult) для создания исключения с указанным ЗНАЧЕНИЕМ HRESULT. Этот метод выполняет поиск значения HRESULT и создает исключение соответствующего типа. Например, в следующем коде для заданного значения HRESULT создается ArgumentException.

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

В следующей таблице приводится общий перечень сопоставлений значений HRESULT с соответствующими классами исключений в .NET. Значения HRESULT без явных сопоставлений сопоставляются с COMException. Актуальные сведения о сопоставлении представлены в репозитории среды выполнения/dotnet.

HRESULT	Исключение .NET
`COR_E_APPLICATION`	`ApplicationException`
`COR_E_ARGUMENT` либо `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`

Чтобы получить дополнительные сведения об ошибке, управляемый клиент должен проверить поля созданного объекта исключения. Чтобы объект исключения содержал полезные сведения об ошибке, COM-объект должен реализовывать интерфейс IErrorInfo. Среда выполнения использует сведения, предоставляемые интерфейсом IErrorInfo, для инициализации объекта исключения.

Если COM-объект не поддерживает интерфейс IErrorInfo, среда выполнения инициализирует объект исключения с использованием значений по умолчанию. В следующей таблице перечислены все поля, связанные с объектом исключения, и указан источник сведений по умолчанию для случаев, когда COM-объект поддерживает IErrorInfo.

Поле Exception	Источник сведений из модели COM
`ErrorCode`	Значение HRESULT, возвращенное из вызова.
`HelpLink`	Если `IErrorInfo->HelpContext` не равно нулю, строка формируется путем сцепления строк `IErrorInfo->GetHelpFile`, "#" и `IErrorInfo->GetHelpContext`. В противном случае возвращается строка из `IErrorInfo->GetHelpFile`.
`InnerException`	Всегда ссылка NULL (`Nothing` в Visual Basic).
`Message`	Строка, возвращаемая `IErrorInfo->GetDescription`.
`Source`	Строка, возвращаемая `IErrorInfo->GetSource`.
`StackTrace`	Трассировка стека.
`TargetSite`	Имя метода, который вернул значение HRESULT со сбоем.

Поля исключения Message, Source и StackTrace недоступны для StackOverflowException.

Практическое руководство. Сопоставление значений HRESULT и исключений

Создание нового класса исключения и его сопоставление со значением HRESULT

См. также

Дополнительные ресурсы

Дополнительные ресурсы