Gestion des erreurs et valeurs de retourError Handling and Return Values

VSPackages et COM utilisent la même architecture pour les erreurs.VSPackages and COM use the same architecture for errors. Le SetErrorInfo et GetErrorInfo fonctions font partie de l’interface de programmation d’application (API) Win32.The SetErrorInfo and GetErrorInfo functions are part of the Win32 application programming interface (API). Un VSPackage dans l’environnement de développement intégré (IDE) peut appeler ces global des API Win32 pour les informations d’erreur complètes enregistrement lors de la réception d’une notification d’erreur.Any VSPackage in the integrated development environment (IDE) can call these global Win32 APIs to record rich error information when receiving an error notification. Le Kit de développement logiciel Visual StudioVisual Studio SDK fournit les assemblys PIA pour gérer les informations d’erreur.The Kit de développement logiciel Visual StudioVisual Studio SDK provides interop assemblies to manage error information.

Méthodes d’interopérabilitéInterop Methods

Pour des raisons pratiques, l’IDE fournit une méthode, SetErrorInfo, à utiliser au lieu d’appeler les API Win32.As a convenience, the IDE provides a method, SetErrorInfo, to use instead of calling the Win32 APIs. En code managé, utilisez SetErrorInfo.In managed code use SetErrorInfo. Lorsqu’une erreur HRESULT arrive au niveau où le message d’erreur doit être affiché (il s’agit souvent de l’objet implémentant un IOleCommandTarget Gestionnaire de commandes), l’IDE utilise une autre méthode, ReportErrorInfo, pour afficher la boîte de message approprié.When an error HRESULT arrives at the level where the error message should be displayed (this is often the object implementing an IOleCommandTarget command handler), the IDE uses another method, ReportErrorInfo, to display the appropriate message box. En code managé, utilisez la ReportErrorInfo (méthode).In managed code use the ReportErrorInfo method.

En tant qu’un implémenteur de VSPackage, vos objets COM implémentent normalement ISupportErrorInfo.As a VSPackage implementer, your COM objects normally implement ISupportErrorInfo. Le ISupportErrorInfo interface garantit que les informations d’erreur complètes peuvent déplacer verticalement de la chaîne d’appel.The ISupportErrorInfo interface ensures that rich error information can move vertically up the call chain. Les objets qui peuvent être utilisées dans les processus ou entre les threads doivent prendre en charge ISupportErrorInfo pour vous assurer que les informations d’erreur détaillée sont correctement marshalées vers l’appelant.Objects that might be used across processes or across threads must support ISupportErrorInfo to ensure that the rich error information is properly marshaled back to the caller.

Tous les objets qui sont liées aux VSPackages et qui sont impliqués dans l’extension de l’IDE, notamment les fabriques d’éditeur, des éditeurs, des hiérarchies et proposé des services, doivent prendre en charge les informations d’erreur complètes.All objects that are related to VSPackages and that are involved in extending the IDE, including editor factories, editors, hierarchies, and offered services, should support rich error information. Bien que l’IDE ne nécessite pas ces objets VSPackage à implémenter ISupportErrorInfo, il est recommandé de toujours.While the IDE does not require these VSPackage objects to implement ISupportErrorInfo, it is always encouraged.

L’IDE est responsable de la consignation des informations sur les erreurs et de les afficher à un utilisateur de Visual StudioVisual Studio chaque fois qu’un HRESULT est propagé à l’IDE.The IDE is responsible for reporting error information and displaying it to a user of Visual StudioVisual Studio whenever an HRESULT is propagated to the IDE. L’IDE est également le mécanisme de création ErrorInfo objets.The IDE is also the mechanism for creating ErrorInfo objects.

Indications généralesGeneral Guidelines

Vous pouvez utiliser la SetErrorInfo et ReportErrorInfo méthodes pour définir et de signaler les erreurs qui sont internes à votre mise en œuvre VSPackage.You can use the SetErrorInfo and ReportErrorInfo methods to set and report errors that are internal to your VSPackage implementation as well. Toutefois, en règle générale, suivez ces instructions pour la gestion des messages d’erreur dans votre VSPackage :However, as a general rule, follow these guidelines for handling error messages in your VSPackage:

  • Implémentez ISupportErrorInfo dans vos objets COM de VSPackage.Implement ISupportErrorInfo in your VSPackage COM objects.

  • Créer une erreur signalant le mécanisme qui appelle le SetErrorInfo méthode dans les objets qui implémentent IOleCommandTarget.Create an error reporting mechanism that calls the SetErrorInfo method in objects that implement IOleCommandTarget.

  • Laisser l’IDE affiche les erreurs aux utilisateurs via le ReportErrorInfo (méthode).Let the IDE display errors to users through the ReportErrorInfo method.

Informations d’erreur dans l’IDEError Information in the IDE

Les règles suivantes indiquent comment gérer les informations d’erreur dans le Visual StudioVisual Studio IDE :The following rules indicate how to handle error information in the Visual StudioVisual Studio IDE:

  • Comme une stratégie pour garantir des informations sur l’erreur obsolète ne sont pas signalée aux utilisateurs, les fonctions qui appellent le ReportErrorInfo méthode doit tout d’abord appeler la SetErrorInfo (méthode).As a defensive strategy to guarantee that stale error info is not reported to users, functions that call the ReportErrorInfo method should first call the SetErrorInfo method. Passez dans null pour effacer les messages d’erreur mis en cache avant l’appel de tout élément qui peut définir de nouvelles informations d’erreur.Pass in null to clear cached error messages before calling anything that might set new error information.

  • Les fonctions qui ne signalent pas directement les messages d’erreur sont uniquement autorisées à appeler le SetErrorInfo méthode si qu’elles renvoient une erreur HRESULT.Functions that do not directly report error messages are only allowed to call the SetErrorInfo method if they are returning an error HRESULT. Il est permis d’effacer le ErrorInfo sur l’entrée à une fonction ou lors du retour S_OK.It is permissible to clear the ErrorInfo on the entry to a function or when returning S_OK. La seule exception à cette règle est lorsqu’un appel retourne une erreur HRESULT à partir de laquelle le destinataire peut récupérer explicitement ou ignorer en toute sécurité.The only exception to this rule is when a call returns an error HRESULT from which the receiving party can explicitly recover or safely ignore.

  • Toute partie qui ignore explicitement une erreur HRESULT doit appeler le SetErrorInfo méthode avec S_OK.Any party that explicitly ignores an error HRESULT must call the SetErrorInfo method with S_OK. Sinon, le ErrorInfo objet peut être accidentellement utilisé lorsqu’une autre partie génère une erreur sans fournir leur propre ErrorInfo.Otherwise, the ErrorInfo object might be accidentally used when another party generates an error without providing their own ErrorInfo.

  • Toutes les méthodes qui proviennent d’une erreur HRESULT est préférable d’appeler le SetErrorInfo méthode pour fournir des informations d’erreur complètes.All methods that originate an error HRESULT are encouraged to call the SetErrorInfo method to provide rich error information. Si le texte retourné HRESULT est spéciale FACILITY_ITF erreur, puis la méthode est nécessaire pour fournir un approprié ErrorInfoobjet.If the returned HRESULT is a special FACILITY_ITF error, then the method is required to provide a proper ErrorInfoobject. Si l’erreur renvoyée est une erreur système standard (par exemple, E_OUTOFMEMORY, E_ABORT, E_INVALIDARG, E_UNEXPECTEDet ainsi de suite.) il est acceptable de retourner le code d’erreur sans appeler explicitement la SetErrorInfo (méthode).If the returned error is a standard system error (for example, E_OUTOFMEMORY, E_ABORT, E_INVALIDARG, E_UNEXPECTED, and so on.) it is acceptable to return the error code without explicitly calling the SetErrorInfo method. En tant qu’une stratégie de codage défensive, lorsqu’une erreur d’origine HRESULT (y compris les erreurs du système), appelez toujours le SetErrorInfo (méthode), soit avec ErrorInfo décrivant l’échec de plus en détail, ou null.As a defensive coding strategy, when originating an error HRESULT (including system errors), always call the SetErrorInfo method, either with ErrorInfo describing the failure in greater detail, or null.

  • Toutes les fonctions qui retournent une erreur d’origine par un autre appel doit transmettre les informations qui a été reçues de l’échec d’appellent le HRESULT sans modifier le ErrorInfo objet.All functions that return an error originated by another call must pass on the information that was received from the failing call in the HRESULT without modifying the ErrorInfo object.

Voir aussiSee Also

IOleCommandTarget
SetErrorInfo (automatisation des composants) SetErrorInfo (Component Automation)
GetErrorInfo GetErrorInfo
Interface ISupportErrorInfoISupportErrorInfo Interface