Guide pratique pour mapper les HRESULTs et les exceptions

Les méthodes COM signalent des erreurs en retournant des HRESULT ; les méthodes .NET les signalent en levant des exceptions. Le runtime gère la transition entre les deux. Chaque classe d’exception dans .NET est mappée à un HRESULT.

Les classes d’exception définies par l’utilisateur peuvent spécifier tout ce qui convient à HRESULT. Ces classes d’exception peuvent modifier dynamiquement le HRESULT à retourner lorsque l’exception est générée en définissant le HResult champ sur l’objet d’exception. Des informations supplémentaires sur l’exception sont fournies au client via l’interfaceIErrorInfo, qui est implémentée sur l’objet .NET dans le processus non managé.

Si vous créez une classe qui s’étend System.Exception, vous devez définir le champ HRESULT pendant la construction. Sinon, la classe de base affecte la valeur HRESULT. Vous pouvez mapper de nouvelles classes d’exception à un HRESULT existant en fournissant la valeur dans le constructeur de l’exception.

Notez que l’environnement d’exécution ignore parfois un HRESULT dans les cas où un IErrorInfo est présent dans le thread. Ce comportement peut se produire dans les cas où le HRESULT et le IErrorInfo ne représentent pas la même erreur.

Pour créer une classe d’exception et la mapper à un HRESULT

1. Utilisez le code suivant pour créer une classe d’exception appelée NoAccessException et la mapper à HRESULT E_ACCESSDENIED.

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

Vous pouvez rencontrer un programme (dans n’importe quel langage de programmation) qui utilise du code managé et non managé en même temps. Par exemple, le marshaler personnalisé dans l’exemple de code suivant utilise la Marshal.ThrowExceptionForHR(int HResult) méthode pour lever une exception avec une valeur HRESULT spécifique. La méthode recherche HRESULT et génère le type d’exception approprié. Par exemple, HRESULT dans le fragment de code suivant génère ArgumentException.

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

Le tableau suivant fournit les mappages courants de HRESULT à sa classe d’exception comparable dans .NET. Les valeurs HRESULT sans mappages explicites sont mappées à COMException. La correspondance complète et à jour est disponible dans le référentiel dotnet/runtime.

Pour récupérer des informations d’erreur étendues, le client géré doit examiner les champs de l’objet d’exception généré. Pour que l’objet d’exception fournisse des informations utiles sur une erreur, l’objet COM doit implémenter l’interface IErrorInfo . L’environnement d’exécution utilise les informations fournies par IErrorInfo pour initialiser l’objet d’exception.

Si l’objet COM ne prend pas en charge IErrorInfo, le runtime initialise un objet d’exception avec des valeurs par défaut. Le tableau suivant répertorie chaque champ associé à un objet d’exception et identifie la source des informations par défaut lorsque l’objet COM prend en charge IErrorInfo.

Notez que l’environnement d’exécution ignore parfois un HRESULT dans les cas où un IErrorInfo est présent sur le thread. Ce comportement peut se produire dans les cas où le HRESULT et le IErrorInfo ne représentent pas la même erreur.

Les champs d’exception, tels que Message, Sourceet StackTrace ne sont pas disponibles pour le StackOverflowException.

Voir aussi

• Interopérabilité COM avancée
• Exceptions