Interfaces supplémentaires C++ du modèle de données du débogueur
Cette rubrique décrit certaines interfaces supplémentaires associées au modèle de données C++ du débogueur, telles que les métadonnées, les concepts et l’énumération d’objets.
Interfaces de métadonnées de modèle de données du débogueur
L’une des notions fondamentales du modèle de données est qu’un objet (en particulier un objet synthétique) est un dictionnaire de tuples clé/valeur/métadonnées. Chaque clé peut avoir un magasin entier de métadonnées qui lui est associé qui décrit une variété d’éléments entourant la clé et sa valeur potentielle. Notez que les métadonnées ne modifient en aucune façon la valeur de la clé. Il s’agit uniquement d’informations accessoires associées à la clé et à sa valeur qui peuvent affecter la présentation ou d’autres attributs associés de la clé et de sa valeur.
Dans certains sens, un magasin de métadonnées n’est pas tout à fait différent des tuples clé/valeur/métadonnées qui constituent l’essence d’un objet dans le modèle de données. Toutefois, il est simplifié à partir de cette vue. Un magasin de métadonnées est représenté par l’interface IKeyStore. Bien qu’il s’agit également d’une collection de tuples clé/valeur/métadonnées, il existe des limites à ce qui peut être fait avec un magasin de clés de métadonnées par rapport à un objet de modèle :
- Un magasin de clés ne peut avoir qu’un seul magasin parent. Il ne peut pas avoir une chaîne arbitraire de modèles parents.
- Un magasin de clés n’a aucun concept. Il ne peut avoir que le dictionnaire de tuples clé/valeur/métadonnées. Cela signifie que les clés présentes dans un magasin de clés sont statiques. Ils ne peuvent pas être créés à la demande par un système de langage dynamique.
- Par convention uniquement, les valeurs d’un magasin de clés défini par métadonnées sont limitées aux valeurs de base (accesseurs de propriété et intrinsèques)
Bien qu’un magasin de clés puisse avoir un nombre arbitraire (et un nommage arbitraire) de clés, certains noms ont des valeurs sémantiques définies. Actuellement, ces noms sont les suivants :
| Nom de la clé | Type de valeur | Description |
|---|---|---|
| PreferredRadix | Entier : 2, 8, 10 ou 16 | Indique le rayon dans lequel une valeur ordinale doit être affichée |
| PreferredFormat | Integer : tel que défini par l’énumération PreferredFormat | Indique le type de mise en forme préféré pour l’affichage de la valeur |
| PreferredLength | Integer | Pour les tableaux et autres conteneurs, indique le nombre d’éléments à afficher par défaut |
| FindDerivation | Boolean | Indique si l’hôte de débogage doit effectuer une analyse de type dérivée sur la valeur avant d’utiliser (par exemple: affichage) |
| Aide | String | Le texte d’aide du style d’info-bulle pour la clé peut être présenté par l’interface utilisateur d’une manière utile. |
| ActionName | String | Indique que la méthode donnée (qui ne prend aucun argument et ne retourne aucune valeur) est une action. Le nom de l’action est spécifié dans les métadonnées. Une interface utilisateur peut utiliser ce nom pour présenter l’option dans un menu contextuel ou une autre interface appropriée |
| ActionIsDefault | Boolean | Valide uniquement si la clé ActionName est spécifiée, indique qu’il s’agit de l’action par défaut pour l’objet . |
| ActionDescription | String | Valide uniquement si la clé ActionName est spécifiée, cela donne une description du style d’info-bulle pour l’action. Ce texte peut être présenté par l’interface utilisateur d’une manière utile. |
Notez que si les clés du magasin de métadonnées peuvent avoir leurs propres métadonnées (ad infiniteum), il n’est actuellement pas utilisé pour ces dernières. La plupart des appelants spécifient null pour tous les paramètres de métadonnées dans les méthodes de l’interface IKeyStore.
Interface de métadonnées principales : IKeyStore
L’interface IKeyStore est définie comme suit :
DECLARE_INTERFACE_(IKeyStore, IUnknown)
{
STDMETHOD(GetKey)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKey)(_In_ PCWSTR key, _In_opt_ IModelObject* object, _In_opt_ IKeyStore* metadata) PURE;
STDMETHOD(GetKeyValue)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKeyValue)(_In_ PCWSTR key, _In_ IModelObject* object) PURE;
STDMETHOD(ClearKeys)() PURE;
}
La méthode GetKey est analogue à la méthode GetKey sur IModelObject. Elle retourne la valeur de la clé spécifiée si elle existe dans le magasin de clés ou le magasin parent du magasin de clés. Notez que si la valeur de la clé est un accesseur de propriété, la méthode GetValue n’est pas appelée sur l’accesseur de propriété. L’IModelPropertyAccessor réel boxé dans un IModelObject est retourné. Il est courant qu’un client appelle GetKeyValue pour cette raison.
La méthode SetKey est analogue à la méthode SetKey sur IModelObject. Il s’agit de la seule méthode capable de créer une clé et de lui associer des métadonnées dans le magasin de clés.
La méthode GetKeyValue est la première méthode qu’un client utilisera pour rechercher la valeur d’une clé particulière dans le magasin de métadonnées. Si la clé spécifiée par l’argument clé existe dans le magasin (ou dans son magasin parent), la valeur de cette clé et toutes les métadonnées qui lui sont associées sont retournées. Si la valeur de la clé est un accesseur de propriété (un IModelPropertyAccessor boxé dans un IModelObject), la méthode GetValue de l’accesseur de propriété est automatiquement appelée par GetKeyValue et la valeur sous-jacente de la propriété retournée.
La méthode SetKeyValue est analogue à la méthode SetKeyValue sur IModelObject. Cette méthode n’est pas capable de créer une clé dans le magasin de métadonnées. S’il existe une clé comme indiqué par l’argument clé, sa valeur est définie comme indiqué. Si la clé est un accesseur de propriété, la méthode SetValue est appelée sur l’accesseur de propriété afin de définir la valeur sous-jacente. Notez que les métadonnées sont généralement statiques une fois créées. L’utilisation de cette méthode sur un magasin de clés de métadonnées doit être peu fréquente.
La méthode ClearKeys est analogue à la méthode ClearKeys sur IModelObject. Elle supprime chaque clé du magasin de métadonnées donné. Cette méthode n’a aucun effet sur un magasin parent.
Énumération d’objets dans le modèle de données
Énumération d’objets dans le modèle de données
Il existe deux interfaces d’énumération clés principales dans le modèle de données : IKeyEnumerator et IRawEnumerator. Bien qu’il s’agit des deux interfaces principales, elles peuvent être utilisées pour énumérer des objets dans l’un des trois styles suivants :
Clés : l’interface IKeyEnumerator peut être acquise via un appel à EnumerateKeys afin d’énumérer les clés d’un objet et leurs valeurs/métadonnées sans résoudre les accesseurs de propriété sous-jacents. Ce style d’énumération peut retourner des valeurs IModelPropertyAccessor brutes boxées dans IModelObjects.
Valeurs : les interfaces IKeyEnumerator et IRawEnumerator peuvent être acquises via des appels à EnumerateKeyValues ou EnumerateRawValues afin d’énumérer les clés/valeurs brutes d’un objet et leurs valeurs/métadonnées. Tous les accesseurs de propriété présents dans l’énumération sont automatiquement résolus via un appel à la méthode GetValue sous-jacente au cours d’une telle énumération.
Références : les interfaces IKeyEnumerator et IRawEnumerator peuvent être acquises via des appels à EnumerateKeyReferences ou EnumerateRawReferences afin d’énumérer les références aux clés/valeurs brutes sur un objet. Ces références peuvent être enregistrées et utilisées ultérieurement pour obtenir ou définir la clé sous-jacente ou la valeur brute.
KeyEnumerator : énumération de clés synthétiques
L’interface IKeyEnumerator est l’interface unique pour l’énumération de toutes les clés (par clé, valeur ou référence) au sein d’un objet instance et de tous les modèles parents associés dans sa chaîne de modèle parent. L’interface se définit comme suit :
DECLARE_INTERFACE_(IKeyEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_ BSTR* key, _COM_Errorptr_opt_ IModelObject** value, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
}
La méthode Reset réinitialise l’énumérateur à la position à laquelle il se trouvait lors de sa première acquisition (par exemple, avant le premier élément de l’énumération). Un appel suivant à GetNext retourne la première clé énumérée.
La méthode GetNext déplace l’énumérateur vers l’avant et retourne la clé à cette position dans l’énumération.
IRawEnumerator : énumération des constructions de langage natif ou sous-jacent (C/C++)
L’interface IRawEnumerator est l’interface unique pour l’énumération de toutes les constructions natives/linguistiques (par valeur ou référence) dans un objet qui représente une construction native dans l’espace d’adressage de la cible de débogage. L’interface se définit comme suit :
DECLARE_INTERFACE_(IRawEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_opt_ BSTR* name, _Out_opt_ SymbolKind *kind, _COM_Errorptr_opt_ IModelObject** value) PURE;
}
La méthode Reset réinitialise l’énumérateur à la position à laquelle il se trouvait lors de sa première acquisition (par exemple, avant le premier élément de l’énumération). Un appel suivant à GetNext retourne la première construction native/de langage énumérée.
La méthode GetNext déplace l’énumérateur vers l’avant et retourne la construction native/linguistique à cette position dans l’énumération.
Voir aussi
Cette rubrique fait partie d’une série qui décrit les interfaces accessibles à partir de C++, comment les utiliser pour créer une extension de débogueur C++ et comment utiliser d’autres constructions de modèle de données (par exemple, JavaScript ou NatVis) à partir d’une extension de modèle de données C++.
Vue d’ensemble du modèle de données C++ du débogueur
Interfaces C++ du modèle de données du débogueur
Objets C++ du modèle de données du débogueur
Interfaces supplémentaires C++ du modèle de données du débogueur
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour