- Exception. HResult Свойство
- Определение
- Значение свойства
- Примеры
- Комментарии
- Практическое руководство. Сопоставление значений HRESULT и исключений How to: Map HRESULTs and Exceptions
- Создание нового класса исключения и его сопоставление со значением HRESULT To create a new exception class and map it to an HRESULT
- HRESULT HRESULT
- Примечания Remarks
Exception. HResult Свойство
Определение
Возвращает или задает HRESULT — кодированное числовое значение, присвоенное определенному исключению. Gets or sets HRESULT, a coded numerical value that is assigned to a specific exception.
Значение свойства
Значение HRESULT. The HRESULT value.
Примеры
В следующем примере кода определяется производный Exception класс, который задает HResult для свойства пользовательское значение в конструкторе. The following code example defines a derived Exception class that sets the HResult property to a custom value in its constructor.
Комментарии
HRESULT — это 32-разрядное значение, разделенное на три разных поля: код серьезности, код средства и код ошибки. HRESULT is a 32-bit value, divided into three different fields: a severity code, a facility code, and an error code. Код серьезности указывает, представляет ли возвращенное значение сведения, предупреждение или ошибку. The severity code indicates whether the return value represents information, warning, or error. Код устройства определяет область системы, из-за которой возникла ошибка. The facility code identifies the area of the system responsible for the error. Код ошибки ― это уникальный номер, представляющий исключение. The error code is a unique number that is assigned to represent the exception. Каждое исключение сопоставляется с отдельным значением HRESULT. Each exception is mapped to a distinct HRESULT. Когда управляемый код создает исключение, среда выполнения передает HRESULT клиенту COM. When managed code throws an exception, the runtime passes the HRESULT to the COM client. Если неуправляемый код возвращает ошибку, значение HRESULT преобразуется в исключение, которое затем выдается средой выполнения. When unmanaged code returns an error, the HRESULT is converted to an exception, which is then thrown by the runtime. Сведения о значениях HRESULT и соответствующих платформа .NET Framework исключениях см. в разделе как сопоставлять значения HRESULT и исключения. For information about HRESULT values and their corresponding .NET Framework exceptions, see How to: Map HRESULTs and Exceptions. Список наиболее часто встречающихся значений см. в разделе Общие значения HRESULT в документации по Windows. See Common HRESULT Values in the Windows documentation for a list of the values you are most likely to encounter.
Начиная с платформа .NET Framework 4,5, HResult метод задания свойства защищен, в то время как его метод получения является открытым. Starting with the .NET Framework 4.5, the HResult property’s setter is protected, whereas its getter is public. В предыдущих версиях платформа .NET Framework и метод получения, и метод задания защищены. In previous versions of the .NET Framework, both getter and setter are protected.
Практическое руководство. Сопоставление значений HRESULT и исключений How to: Map HRESULTs and Exceptions
Методы COM сообщают об ошибках, возвращая значения HRESULT. Методы .NET в этом случае вызывают исключения. 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. Дополнительные сведения об исключении предоставляются клиенту посредством интерфейса IErrorInfo , который реализуется для объекта .NET в неуправляемом процессе. 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.
Обратите внимание, что среда выполнения в некоторых случаях будет игнорировать значение HRESULT , если в потоке присутствует IErrorInfo . Note that the runtime will sometimes ignore an HRESULT in cases where there is an IErrorInfo present on the thread. Это возможно в тех случаях, когда HRESULT и IErrorInfo представляют разные ошибки. 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
В следующем коде создается новый класс исключения NoAccessException , который сопоставляется со значением HRESULT E_ACCESSDENIED . Use the following code to create a new exception class called NoAccessException and map it to the HRESULT E_ACCESSDENIED .
На любом языке программирования могут встречаться программы, в которых одновременно используется управляемый и неуправляемый код. 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. 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 .
В следующей таблице приводится общий перечень сопоставлений значений 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. The complete up-to-date mapping can be found in the dotnet/runtime repository.
| HRESULT HRESULT | Исключение .NET .NET exception |
|---|---|
| COR_E_APPLICATION | ApplicationException |
| COR_E_ARGUMENT либо E_INVALIDARG COR_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 .
Обратите внимание, что среда выполнения в некоторых случаях будет игнорировать значение HRESULT , если в потоке присутствует IErrorInfo . Note that the runtime will sometimes ignore an HRESULT in cases where there is an IErrorInfo present on the thread. Это возможно в тех случаях, когда HRESULT и IErrorInfo представляют разные ошибки. This behavior can occur in cases where the HRESULT and the IErrorInfo do not represent the same error.
| Поле Exception Exception field | Источник сведений из модели COM Source of Information from COM |
|---|---|
| ErrorCode | Значение HRESULT, возвращенное из вызова. HRESULT returned from call. |
| HelpLink | Если IErrorInfo->HelpContext не равно нулю, строка формируется путем сцепления строк 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 ( Nothing в Visual Basic). 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 , Source и StackTrace недоступны для StackOverflowException . Exception fields, such as Message , Source , and StackTrace are not available for the StackOverflowException .
HRESULT HRESULT
Относится к: Outlook 2013 | Outlook 2016 Applies to: Outlook 2013 | Outlook 2016
32-битное значение, которое используется для описания ошибки или предупреждения. A 32-bit value that is used to describe an error or warning.
Примечания Remarks
Тип данных HRESULT такой же, как и тип данных SCODE. The HRESULT data type is the same as the SCODE data type.
Значение HRESULT состоит из следующих полей: An HRESULT value consists of the following fields:
1-битный код, указывающий серьезность, где ноль означает успех, а 1 — сбой. A 1-bit code indicating severity, where zero represents success and 1 represents failure.
4-битное зарезервированное значение. A 4-bit reserved value.
11-битный код, указывающий ответственность за ошибку или предупреждение, также известный как код объекта. An 11-bit code indicating responsibility for the error or warning, also known as a facility code.
16-битный код, описывающий ошибку или предупреждение. A 16-bit code describing the error or warning.
Большинство методов и функций интерфейса MAPI возвращают значения HRESULT, чтобы предоставить подробные сведения о причинах. Most MAPI interface methods and functions return HRESULT values to provide detailed cause formation. Значения HRESULT также широко используются в методах интерфейса OLE. HRESULT values are also used widely in OLE interface methods. OLE предоставляет несколько макроса для преобразования значений HRESULT в значения SCODE, еще один распространенный тип данных для обработки ошибок. OLE provides several macros for converting between HRESULT values and SCODE values, another common data type for error handling.
В 64-битных MAPI HRESULT по-прежнему является 32-битным значением. In 64-bit MAPI, HRESULT is still a 32-bit value.
Сведения об использовании значений HRESULT в OLE см. в справочнике по OLE Programmer. For information about the OLE use of HRESULT values, see the OLE Programmer’s Reference . Дополнительные сведения об использовании этих значений в MAPI см. в обработке ошибок и любом из следующих методов интерфейса: For more information about the use of these values in MAPI, see Error Handling and any of the following interface methods:
