Note
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier les répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de changer de répertoire.
Cette rubrique explique comment utiliser le modèle de données du débogueur C++ pour prendre en charge l’automatisation avec le moteur de débogueur à l’aide de scripts.
Gestion des scripts dans le modèle de données du débogueur
Outre le rôle du Gestionnaire de modèles de données en tant qu’autorité centrale sur la création et l’extensibilité des objets, il est également responsable de la gestion d’un concept abstrait de scripts. Du point de vue de la partie Gestionnaire de scripts du Gestionnaire de modèles de données, un script est un script qui peut être chargé, déchargé et potentiellement débogué par un fournisseur afin d’étendre ou de fournir de nouvelles fonctionnalités au modèle de données.
Un fournisseur de scripts est un composant qui relie un langage (par exemple, NatVis, JavaScript, etc.) au modèle de données. Il inscrit une ou plusieurs extensions de fichier (par exemple : « ». NatVis , «.js») qui sont gérés par le fournisseur permettant à un client de débogueur ou à une interface utilisateur de permettre le chargement de fichiers de script avec cette extension particulière par délégation au fournisseur.
Core Script Manager : IDataModelScriptManager
L’interface principale du gestionnaire de scripts est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptManager, IUnknown)
{
STDMETHOD(GetDefaultNameBinder)(_COM_Outptr_ IDataModelNameBinder **ppNameBinder) PURE;
STDMETHOD(RegisterScriptProvider)(_In_ IDataModelScriptProvider *provider) PURE;
STDMETHOD(UnregisterScriptProvider)(_In_ IDataModelScriptProvider *provider) PURE;
STDMETHOD(FindProviderForScriptType)(_In_ PCWSTR scriptType, _COM_Outptr_ IDataModelScriptProvider **provider) PURE;
STDMETHOD(FindProviderForScriptExtension)(_In_ PCWSTR scriptExtension, _COM_Outptr_ IDataModelScriptProvider **provider) PURE;
STDMETHOD(EnumerateScriptProviders)(_COM_Outptr_ IDataModelScriptProviderEnumerator **enumerator) PURE;
}
La méthode GetDefaultNameBinder retourne le classeur de noms de script par défaut du modèle de données. Un classeur de noms est un composant qui résout un nom dans le contexte d’un objet. Par exemple, étant donné l’expression « foo.bar », un classeur de noms est appelé pour résoudre la barre de noms dans le contexte de foo d’objet. Le classeur retourné ici suit un ensemble de règles par défaut pour le modèle de données. Les fournisseurs de script peuvent utiliser ce classeur pour assurer la cohérence dans la résolution de noms entre les fournisseurs.
La méthode RegisterScriptProvider informe le modèle de données qu’un nouveau fournisseur de scripts existe, capable de combler un nouveau langage vers le modèle de données. Lorsque cette méthode est appelée, le gestionnaire de scripts rappelle immédiatement le fournisseur de scripts donné et s’interroge sur les propriétés des scripts qu’il gère. S’il existe déjà un fournisseur inscrit sous le nom ou l’extension de fichier que le fournisseur de script donné indique, cette méthode échoue. Un seul fournisseur de scripts peut être inscrit en tant que gestionnaire pour un nom ou une extension de fichier particulier.
La méthode UnregisterScriptProvider annule un appel à la méthode RegisterScriptProvider. Le nom et l’extension de fichier donnés par le fournisseur de script passé ne seront plus associés à celui-ci. Il est important de noter qu’il peut y avoir un nombre important de références COM en attente au fournisseur de scripts, même après l’annulation de l’inscription. Cette méthode empêche uniquement le chargement/la création de scripts du type que le fournisseur de scripts donné gère. Si un script chargé par ce fournisseur est toujours chargé ou a manipulé le modèle objet du débogueur (ou modèle de données), ces manipulations peuvent toujours avoir des références dans le script. Il peut y avoir des modèles de données, des méthodes ou des objets qui référencent directement des constructions dans le script. Un fournisseur de scripts doit être prêt à traiter cela.
La méthode FindProviderForScriptType recherche le gestionnaire de scripts pour un fournisseur qui a une chaîne de type de script, comme indiqué dans cette méthode. Si l’un d’eux est introuvable, cette méthode échoue ; sinon, ce fournisseur de script est retourné à l’appelant.
La méthode EnumerateScriptProviders retourne un énumérateur qui énumère chaque fournisseur de scripts inscrit auprès du gestionnaire de scripts via un appel antérieur à la méthode RegisterScriptProvider.
énumération du fournisseur de scripts : IDataModelScriptProviderEnumerAtor
La méthode EnumerateScriptProviders retourne un énumérateur du formulaire suivant :
DECLARE_INTERFACE_(IDataModelScriptProviderEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptProvider **provider) PURE;
}
La méthode Reset déplace l’énumérateur vers la position à laquelle elle était avant de retourner le premier élément.
La méthode GetNext déplace l’énumérateur vers l’avant un élément et retourne le fournisseur de script qui se trouve à cet élément. Lorsque l’énumérateur atteint la fin de l’énumération, E_BOUNDS est retourné. L’appel de la méthode GetNext après avoir reçu cette erreur continuera à retourner E_BOUNDS indéfiniment.
les interfaces hôtes C++ du modèle de données du débogueur pour l’écriture de scripts
rôle de l’hôte dans le de script
L’hôte de débogage expose une série d’interfaces de niveau très bas pour comprendre la nature du système de type de ses cibles de débogage, l’évaluation des expressions dans le langage de sa ou ses cibles de débogage, etc. Normalement, il n’est pas pris en compte avec des constructions de niveau supérieur comme le script. Cela est laissé à l’application de débogueur globale ou aux extensions qui fournissent ces fonctionnalités. Toutefois, il existe une exception à ceci. Tout hôte de débogage qui souhaite participer à l’expérience globale de script offerte par le modèle de données doit implémenter quelques interfaces simples pour fournir des contextes aux scripts. En effet, l’hôte de débogage contrôle l’emplacement où il souhaite que l’environnement de script place les fonctions et d’autres fonctionnalités fournies par un script dans l’espace de noms du modèle de données. L’implication dans ce processus permet à l’hôte d’autoriser (ou non) l’utilisation de ces fonctions dans, par exemple, son évaluateur d’expression. Les interfaces impliquées du point de vue de l’hôte sont les suivantes :
| Interface | Description |
|---|---|
| IDebugHostScriptHost | Interface qui indique la capacité de l’hôte de débogage à participer à l’environnement de script. Cette interface permet de créer des contextes qui informent les moteurs de script d’où placer des objets. |
| IDataModelScriptHostContext | Interface hôte utilisée par le fournisseur de scripts comme conteneur pour le contenu du script. Comment le contenu d’une surface de script autre que les manipulations qu’il effectue sur le modèle objet de l’application de débogueur est jusqu’à l’hôte de débogage particulier. Cette interface permet au fournisseur de scripts d’obtenir des informations sur l’emplacement où placer son contenu. Pour plus d’informations, consultez interfaces de script C++ du modèle de données plus loin dans cette rubrique. |
l’hôte de script de l’hôte de débogage : IDebugHostScriptHost
L’interface IDebugHostScriptHost est l’interface utilisée par un fournisseur de scripts pour obtenir un contexte à partir de l’hôte de débogage pour un script nouvellement créé. Ce contexte inclut un objet (fourni par l’hôte de débogage) dans lequel le fournisseur de scripts peut placer des ponts entre le modèle de données et l’environnement de script. Ces ponts peuvent, par exemple, être des méthodes de modèle de données qui appellent des fonctions de script. Cela permet à un appelant côté modèle de données d’appeler des méthodes de script en utilisant la méthode Call sur l’interface IModelMethod.
L’interface IDebugHostScriptHost est définie comme suit.
DECLARE_INTERFACE_(IDebugHostScriptHost, IUnknown)
{
STDMETHOD(CreateContext)(_In_ IDataModelScript* script, _COM_Outptr_ IDataModelScriptHostContext** scriptContext) PURE;
}
La méthode CreateContext est appelée par un fournisseur de scripts pour créer un contexte dans lequel placer le contenu du script. Ce contexte est représenté par l’interface IDataModelScriptHostContext décrite en détail dans la page Interfaces de script C++ du modèle de données.
interfaces de script C++ du modèle de données du débogueur
scripts et interfaces de script
L’architecture globale du modèle de données permet à un tiers de définir un pont entre un certain langage et le modèle objet du modèle de données. En règle générale, le langage en cours de pont est un langage de script, car l’environnement du modèle de données est très dynamique. Un composant qui définit et implémente ce pont entre un langage et le modèle objet du modèle de données est appelé fournisseur de script. Lorsqu’il est initialisé, un fournisseur de scripts s’inscrit auprès de la partie gestionnaire de scripts du gestionnaire de modèles de données et de toute interface qui gère l’extensibilité permet par la suite de modifier, charger, décharger et déboguer potentiellement des scripts écrits dans le langage que le fournisseur de scripts gère.
Notez que les outils de débogage pour Windows définissent actuellement deux fournisseurs de script.
- Fournisseur NatVis. Ce fournisseur est incorporé dans DbgEng.dll et les ponts entre natVis XML et les modèles de données, ce qui permet la visualisation des types de données natifs/linguistiques.
- Fournisseur JavaScript. Ce fournisseur est contenu dans une extension de débogueur héritée : JsProvider.dll. Il relie les scripts écrits dans le langage JavaScript et le modèle de données, ce qui permet des formes arbitraires de contrôle et d’extensibilité du débogueur.
De nouveaux fournisseurs peuvent être écrits qui pontent d’autres langages (par exemple, Python, etc.) vers le modèle de données. Cela serait actuellement encapsulé dans les extensions de débogueur héritées à des fins de chargement. Le fournisseur de script lui-même doit réduire la dépendance avec les interfaces de moteur héritées et ne doit utiliser que les API de modèle de données si possible. Cela permettra au fournisseur d’être rendu portable dans d’autres environnements avec beaucoup plus de facilité.
Il existe deux classes d’interfaces liées aux fournisseurs de script. La première classe d’interfaces est la gestion générale des fournisseurs de scripts et les scripts qu’ils gèrent. La deuxième classe d’interfaces est la prise en charge du débogage de script. Bien que la prise en charge du premier ensemble soit obligatoire, la prise en charge de la seconde est facultative et peut ne pas avoir de sens pour chaque fournisseur.
Les interfaces de gestion générales sont les suivantes :
| Interface | Description |
|---|---|
| IDataModelScriptProvider | Interface principale qu’un fournisseur de scripts doit implémenter. Il s’agit de l’interface qui est inscrite auprès de la partie gestionnaire de scripts du gestionnaire de modèles de données afin de publier la prise en charge du fournisseur d’un type particulier de script et de s’inscrire auprès d’une extension de fichier particulière |
| IDataModelScript | Abstraction d’un script particulier géré par le fournisseur. Chaque script chargé ou en cours de modification a une instance IDataModelScript distincte |
| IDataModelScriptClient | Interface cliente utilisée par le fournisseur de scripts pour communiquer des informations à une interface utilisateur. Les fournisseurs de script n’implémentent pas cette interface. L’application hébergeant le modèle de données qui souhaite utiliser des fournisseurs de script. Un fournisseur de scripts appelle les méthodes du client de script pour signaler l’état, les erreurs, etc. |
| IDataModelScriptHostContext | Interface hôte utilisée par le fournisseur de scripts comme conteneur pour le contenu du script. Comment le contenu d’une surface de script autre que les manipulations qu’il effectue sur le modèle objet de l’application de débogueur est jusqu’à l’hôte de débogage particulier. Cette interface permet au fournisseur de scripts d’obtenir des informations sur l’emplacement où placer son contenu. |
| IDataModelScriptTemplate | Les fournisseurs de scripts peuvent fournir un ou plusieurs modèles qui servent de points de départ aux utilisateurs pour créer des scripts. Une application de débogueur qui fournit un éditeur intégré peut préremplir de nouveaux scripts avec du contenu de modèle tel qu’annoncé par le fournisseur via cette interface. |
| IDataModelScriptTemplateEnumerator | Interface d’énumérateur que le fournisseur de scripts implémente afin de publier tous les différents modèles qu’il prend en charge. |
| IDataModelNameBinder | Classeur de noms : objet qui peut associer un nom dans un contexte à une valeur. Pour une expression donnée telle que « foo.bar », un classeur de noms peut lier le nom « bar » dans le contexte de l’objet « foo » et produire une valeur ou une référence à celui-ci. Les classeurs de noms ne sont généralement pas implémentés par un fournisseur de scripts ; au lieu de cela, le classeur par défaut peut être acquis à partir du modèle de données et utilisé par le fournisseur de scripts |
Les interfaces de débogage sont les suivantes :
| Interface | Description |
|---|---|
| IDataModelScriptDebug | Interface principale qu’un fournisseur de scripts doit fournir pour rendre un script débogueurable. La classe d’implémentation de l’interface IDataModelScript doit QueryInterface pour IDataModelScriptDebug si le script est débogueur. |
| IDataModelScriptDebugClient | L’interface utilisateur qui souhaite fournir la fonctionnalité de débogage de script implémente l’interface IDataModelScriptDebugClient. Le fournisseur de scripts utilise cette interface pour transmettre des informations de débogage de retour et de sortie (par exemple, les événements qui se produisent, les points d’arrêt, etc.) |
| IDataModelScriptDebugStack | Le fournisseur de scripts implémente cette interface pour exposer la notion de pile d’appels au débogueur de script. |
| IDataModelScriptDebugStackFrame | Le fournisseur de scripts implémente cette interface pour exposer la notion d’une trame de pile particulière dans la pile des appels. |
| IDataModelScriptDebugVariableSetEnumerator | Le fournisseur de scripts implémente cette interface pour exposer un ensemble de variables. Cet ensemble peut représenter l’ensemble de paramètres d’une fonction, l’ensemble de variables locales ou l’ensemble de variables dans une étendue particulière. La signification exacte dépend de la façon dont l’interface a été acquise. |
| IDataModelScriptDebugBreakpoint | Le fournisseur de scripts implémente cette interface pour exposer la notion et le contrôle d’un point d’arrêt particulier dans le script. |
| IDataModelScriptDebugBreakpointEnumerator | Le fournisseur de scripts implémente ceci pour énumérer tous les points d’arrêt qui existent actuellement dans le script (activés ou non). |
Le fournisseur de script principal : IDataModelScriptProvider
Toute extension qui souhaite être un fournisseur de scripts doit fournir une implémentation de l’interface IDataModelScriptProvider et l’inscrire auprès de la partie gestionnaire de scripts du gestionnaire de modèles de données via la méthode RegisterScriptProvider. Cette interface principale qui doit être implémentée est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptProvider, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *name) PURE;
STDMETHOD(GetExtension)(_Out_ BSTR *extension) PURE;
STDMETHOD(CreateScript)(_COM_Outptr_ IDataModelScript **script) PURE;
STDMETHOD(GetDefaultTemplateContent)(_COM_Outptr_ IDataModelScriptTemplate **templateContent) PURE;
STDMETHOD(EnumerateTemplates)(_COM_Outptr_ IDataModelScriptTemplateEnumerator **enumerator) PURE;
}
La méthode GetName retourne le nom du type (ou du langage) des scripts que le fournisseur gère en tant que chaîne allouée via la méthode SysAllocString. L’appelant est chargé de libérer la chaîne retournée via SysFreeString. Exemples de chaînes qui peuvent être retournées à partir de cette méthode sont « JavaScript » ou « NatVis ». La chaîne retournée est susceptible d’apparaître dans l’interface utilisateur de l’application de débogueur qui héberge le modèle de données. Aucun fournisseur de script ne peut retourner le même nom (sans respect de la casse).
La méthode GetExtension retourne l’extension de fichier pour les scripts gérés par ce fournisseur (sans point) sous forme de chaîne allouée via la méthode SysAllocString. L’application débogueur hébergeant le modèle de données (avec prise en charge des scripts) déléguera l’ouverture de fichiers de script avec cette extension au fournisseur de scripts. L’appelant est chargé de libérer la chaîne retournée via SysFreeString. Exemples de chaînes qui peuvent être retournées à partir de cette méthode sont « js » ou « NatVis ».
La méthode CreateScript est appelée pour créer un script. Le fournisseur de scripts doit retourner un script nouveau et vide représenté par l’interface IDataModelScript retournée chaque fois que cette méthode est appelée. Notez que cette méthode est appelée, que l’interface utilisateur crée un script vide pour la modification par l’utilisateur ou si l’application de débogueur charge un script à partir du disque. Le fournisseur n’est pas impliqué dans les E/S de fichier. Il gère simplement les requêtes de l’application d’hébergement via des flux transmis aux méthodes sur IDataModelScript.
La méthode GetDefaultTemplateContent retourne une interface pour le contenu du modèle par défaut du fournisseur. Il s’agit du contenu que le fournisseur de scripts souhaite préremplie dans une fenêtre d’édition pour un script nouvellement créé. Si le fournisseur de scripts n’a aucun modèle (ou n’a pas de contenu de modèle désigné comme contenu par défaut), le fournisseur de scripts peut retourner E_NOTIMPL de cette méthode.
La méthode EnumerateTemplates retourne un énumérateur capable d’énumérer la variété de modèles fournis par le fournisseur de scripts. Le contenu du modèle est ce que le fournisseur de scripts souhaite être « prérempli » dans une fenêtre d’édition lors de la création d’un script. S’il existe plusieurs modèles pris en charge, ces modèles peuvent être nommés (par exemple : « Script impératif », « Script d’extension ») et l’application de débogueur hébergeant le modèle de données peut choisir comment présenter les « modèles » à l’utilisateur.
l’interface de script principale : IDataModelScript
L’interface principale qui gère un script individuel implémenté par le fournisseur est l’interface IDataModelScript. Un composant implémentant cette interface est retourné lorsque le client souhaite créer un script vide et appelle la méthode CreateScript sur IDataModelScriptProvider.
Chaque script créé par le fournisseur doit se trouver dans un silo indépendant. Un script ne doit pas être en mesure d’affecter un autre script, à l’exception d’une interaction explicite avec des objets externes via le modèle de données. Deux scripts, par exemple, peuvent étendre à la fois un type ou un concept (par exemple : la notion du débogueur de ce qu’est un processus). L’un ou l’autre script peut ensuite accéder aux champs des uns des autres via l’objet de processus externe.
L’interface est définie comme suit.
DECLARE_INTERFACE_(IDataModelScript, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *scriptName) PURE;
STDMETHOD(Rename)(_In_ PCWSTR scriptName) PURE;
STDMETHOD(Populate)(_In_ IStream *contentStream) PURE;
STDMETHOD(Execute)(_In_ IDataModelScriptClient *client) PURE;
STDMETHOD(Unlink)() PURE;
STDMETHOD(IsInvocable)(_Out_ bool *isInvocable) PURE;
STDMETHOD(InvokeMain)(_In_ IDataModelScriptClient *client) PURE;
}
La méthode GetName retourne le nom du script en tant que chaîne allouée via la fonction SysAllocString. Si le script n’a pas encore de nom, la méthode doit retourner une valeur BSTR null. Il ne devrait pas échouer dans cette situation. Si le script est explicitement renommé via un appel à la méthode Rename, la méthode GetName doit retourner le nom qui vient d’être attribué.
La méthode Rename attribue un nouveau nom au script. Il incombe à l’implémentation du script d’enregistrer ce nom et de le retourner à tout appel à la méthode GetName. Cela est souvent appelé lorsqu’une interface utilisateur choisit d’enregistrer sous le script dans un nouveau nom. Notez que le changement de nom du script peut affecter l’emplacement où l’application d’hébergement choisit de projeter le contenu du script.
La méthode Populate est appelée par le client pour modifier ou synchroniser le « contenu » du script. Il s’agit de la notification envoyée au fournisseur de script que le code du script a changé. Il est important de noter que cette méthode n’entraîne pas l’exécution du script ou des modifications apportées à l’un des objets que le script manipule. Il s’agit simplement d’une notification au fournisseur de script que le contenu du script a changé afin qu’il puisse synchroniser son propre état interne.
La méthode Execute exécute le contenu du script tel qu’il est dicté par le dernier appel de remplissage réussi et modifie le modèle objet du débogueur en fonction de ce contenu. Si le langage (ou le fournisseur de scripts) définit une « fonction principale », l’une que l’auteur souhaiterait appeler en cliquant sur un bouton imaginaire « Exécuter le script » dans une interface utilisateur , ce type de « fonction principale » n’est pas appelé lors d’une opération d’exécution. L’opération d’exécution peut être considérée comme effectuant uniquement des manipulations d’initialisation et de modèle objet (par exemple, l’exécution du code racine et la configuration de points d’extensibilité).
La méthode Unlink annule l’opération Execute. Toutes les manipulations de modèle objet ou points d’extensibilité établis pendant l’exécution du script sont annulées. Après une opération de dissociation, le script peut être réexécuté via un appel à Exécuter ou il peut être libéré.
La méthode IsInvocable retourne si le script est invocable, c’est-à-dire qu’il a une « fonction principale » telle que définie par son langage ou son fournisseur. Une telle « fonction principale » est conceptuellement quelque chose que l’auteur de script souhaite appeler si un bouton imaginaire « Exécuter un script » a été appuyé dans une interface utilisateur.
Si le script a une « fonction principale » qui est destinée à s’exécuter à partir d’un appel d’interface utilisateur, elle indique cela par le biais d’un retour réel de la méthode IsInvocable. L’interface utilisateur peut ensuite appeler la méthode InvokeMain pour « appeler » réellement le script. Notez que cela est distinct de Exécuter qui exécute tout le code racine et relie le script à l’espace de noms de l’hôte sous-jacent.
**Le client de script : IDataModelScriptClient **
Une application hébergeant le modèle de données qui souhaite gérer des scripts et avoir une interface utilisateur (graphique ou console) autour de cette notion implémente l’interface IDataModelScriptClient. Cette interface est transmise à n’importe quel fournisseur de scripts lors de l’exécution ou de l’appel ou d’un script afin de transmettre des informations d’erreur et d’événement à l’interface utilisateur.
L’interface IDataModelScriptClient est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptClient, IUnknown)
{
STDMETHOD(ReportError)(_In_ ErrorClass errClass, _In_ HRESULT hrFail, _In_opt_ PCWSTR message, _In_ ULONG line, _In_ ULONG position) PURE;
}
Si une erreur se produit pendant l’exécution ou l’appel du script, le fournisseur de scripts appelle la méthode ReportError pour notifier l’interface utilisateur de l’erreur.
Le contexte hôte d’un script : IDataModelScriptHostContext
L’hôte de débogage a une influence sur la façon et l’emplacement où il projette le contenu du script de modèle de données. On s’attend à ce que chaque script demande à l’hôte un contexte dans lequel placer des ponts vers le script (par exemple, les objets de fonction qui peuvent être appelés, etc.). Ce contexte est récupéré via l’appel de la méthode CreateContext sur IDebugHostScriptHost et l’obtention d’un IDataModelScriptHostContext.
L’interface IDataModelScriptHostContext est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptHostContext, IUnknown)
{
STDMETHOD(NotifyScriptChange)(_In_ IDataModelScript* script, _In_ ScriptChangeKind changeKind) PURE;
STDMETHOD(GetNamespaceObject)(_COM_Outptr_ IModelObject** namespaceObject) PURE;
}
Il est nécessaire qu’un fournisseur de scripts notifie l’hôte de débogage lors de certaines opérations effectuées avec un appel de méthode à la méthode NotifyScriptChange sur le contexte associé. Ces opérations sont définies en tant que membres de l’énumération ScriptChangeKind
La méthode GetNamespaceObject retourne un objet dans lequel le fournisseur de scripts peut placer des ponts entre le modèle de données et le script. C’est ici, par exemple, que le fournisseur de scripts peut placer des objets de méthode de modèle de données (interfaces IModelMethod boxées dans IModelObject) dont l’implémentation appelle des fonctions nommées correspondantes dans le script.
modèles pour les scripts nouvellement créés : IDataModelScriptTemplate
Les fournisseurs de scripts qui souhaitent présenter du contenu prérempli pour de nouveaux scripts (par exemple, pour aider les utilisateurs à écrire des scripts dans une interface utilisateur du débogueur) peuvent le faire en fournissant un ou plusieurs modèles de script. Ces modèles sont des composants qui implémentent l’interface IDataModelScriptTemplate et sont retournés via la méthode GetDefaultTemplate ou la méthode EnumerateTemplates sur le fournisseur de scripts.
L’interface IDataModelScriptTemplate est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptTemplate, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *templateName) PURE;
STDMETHOD(GetDescription)(_Out_ BSTR *templateDescription) PURE;
STDMETHOD(GetContent)(_COM_Outptr_ IStream **contentStream) PURE;
}
La méthode GetName retourne un nom du modèle. Cela peut échouer avec E_NOTIMPL si le modèle n’a pas de nom. Le modèle par défaut unique (s’il en existe) n’est pas requis pour avoir un nom. Tous les autres modèles sont. Ces noms peuvent être présentés dans une interface utilisateur dans le cadre d’un menu pour sélectionner le modèle à créer.
La méthode GetDescription retourne une description du modèle. Cette description serait présentée à l’utilisateur dans des interfaces plus descriptives pour aider l’utilisateur à comprendre ce que le modèle est conçu pour le faire. Le modèle peut retourner E_NOTIMPL de cette méthode s’il n’a pas de description.
La méthode GetContent retourne le contenu (ou le code) du modèle. Il s’agit de ce qui serait prérempli dans la fenêtre d’édition si un utilisateur a choisi de créer un script à partir de ce modèle. Le modèle est responsable de la création (et du retour) d’un flux standard sur le contenu que le client peut extraire.
énumération du contenu du modèle d’un fournisseur : IDataModelScriptTemplateEnumerator
Un fournisseur de scripts peut fournir un ou plusieurs modèles qui préremplent du contenu dans des scripts nouvellement créés dans une interface utilisateur. Si l’un de ces modèles est fourni, le fournisseur de scripts doit implémenter un énumérateur sur eux qui est retourné lors d’un appel à la méthode EnumerateTemplates.
Cet énumérateur est une implémentation de l’interface IDataModelScriptTemplateEnumerator et est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptTemplateEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptTemplate **templateContent) PURE;
}
La méthode Reset réinitialise l’énumérateur à la position à laquelle elle était créée pour la première fois, avant que le premier modèle ne soit produit.
La méthode GetNext déplace l’énumérateur vers le modèle suivant et la retourne. À la fin de l’énumération, l’énumérateur retourne E_BOUNDS. Une fois le marqueur E_BOUNDS atteint, l’énumérateur continue de produire des erreurs E_BOUNDS indéfiniment jusqu’à ce qu’un appel de réinitialisation soit effectué.
Résolution de la signification des noms : IDataModelNameBinder
Le modèle de données fournit un moyen standard pour les fournisseurs de script de déterminer la signification d’un nom donné dans un contexte donné (par exemple, déterminer les moyens de la barre pour foo.bar) qui fonctionnent sur divers fournisseurs de scripts. Ce mécanisme est appelé classeur de noms et est représenté par l’interface IDataModelNameBinder. Un tel classeur encapsule un ensemble de règles sur la façon dont le nom est résolu et comment traiter la résolution des conflits où un nom est défini plusieurs fois sur un objet. Une partie de ces règles inclut des éléments tels que la façon dont un nom projeté (un ajouté par un modèle de données) se résout par rapport à un nom natif (un dans le système de type du langage en cours de débogage).
Pour fournir un degré de cohérence entre les fournisseurs de scripts, le gestionnaire de scripts du modèle de données fournit un classeur de noms par défaut. Ce classeur de noms par défaut peut être acquis via un appel à la méthode GetDefaultNameBinder sur l’interface IDataModelScriptManager. L’interface du classeur de noms est définie comme suit.
DECLARE_INTERFACE_(IDataModelNameBinder, IUnknown)
{
STDMETHOD(BindValue)(_In_ IModelObject* contextObject, _In_ PCWSTR name, _COM_Errorptr_ IModelObject** value, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(BindReference)(_In_ IModelObject* contextObject, _In_ PCWSTR name, _COM_Errorptr_ IModelObject** reference, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(EnumerateValues)(_In_ IModelObject* contextObject, _COM_Outptr_ IKeyEnumerator** enumerator) PURE;
STDMETHOD(EnumerateReferences)(_In_ IModelObject* contextObject, _COM_Outptr_ IKeyEnumerator** enumerator) PURE;
}
La méthode BindValue effectue l’équivalent de contextObject.name sur l’objet donné en fonction d’un ensemble de règles de liaison. Le résultat de cette liaison est une valeur. En tant que valeur, le fournisseur de script sous-jacent ne peut pas utiliser la valeur pour effectuer l’affectation de nouveau au nom.
La méthode BindReference est similaire à BindValue, car elle effectue également l’équivalent de contextObject.name sur l’objet donné en fonction d’un ensemble de règles de liaison. Le résultat de la liaison de cette méthode est toutefois une référence au lieu d’une valeur. En guise de référence, le fournisseur de scripts peut utiliser la référence pour effectuer une affectation de nouveau au nom.
La méthode EnumerateValues énumère l’ensemble de noms et de valeurs qui seront liés à l’objet en fonction des règles de la méthode BindValue. Contrairement aux EnumerateKeys, EnumerateValues et méthodes similaires sur IModelObject, qui peuvent retourner plusieurs noms avec la même valeur (pour les classes de base, les modèles parents et les modèles similaires), cet énumérateur retourne uniquement l’ensemble spécifique de noms qui sera lié à BindValue et BindReference. Les noms ne seront jamais dupliqués. Notez qu’il existe un coût beaucoup plus élevé d’énumération d’un objet via le classeur de noms que l’appel des méthodes IModelObject.
La méthode EnumerateReferences énumère l’ensemble de noms et de références à ceux-ci qui seront liés à l’objet en fonction des règles de la méthode BindReference. Contrairement aux EnumerateKeys, EnumerateValues et méthodes similaires sur IModelObject, qui peuvent retourner plusieurs noms avec la même valeur (pour les classes de base, les modèles parents et les modèles similaires), cet énumérateur retourne uniquement l’ensemble spécifique de noms qui sera lié à BindValue et BindReference. Les noms ne seront jamais dupliqués. Notez qu’il existe un coût beaucoup plus élevé d’énumération d’un objet via le classeur de noms que l’appel des méthodes IModelObject.
interfaces de débogage de modèle de données du débogueur C++
L’infrastructure des fournisseurs de scripts dans le modèle de données fournit également un concept autour du débogage des scripts. Tout script qui souhaite exposer les fonctionnalités de débogage à l’hôte de débogage et à l’application de débogueur hébergeant le modèle de données peut le faire en ayant des scripts débogueurs implémentant l’interface IDataModelScriptDebug en plus de l’interface IDataModelScript. La présence de cette interface sur le script indique à l’infrastructure qu’elle est débogueur.
Bien que l’interface IDataModelScriptDebug soit le point de départ pour accéder aux fonctionnalités de débogage d’un fournisseur de scripts, elle est jointe par un ensemble d’autres interfaces pour fournir des fonctionnalités de débogage globales.
Les interfaces de débogage sont les suivantes :
| Interface | Description |
|---|---|
| IDataModelScriptDebug | Interface principale qu’un fournisseur de scripts doit fournir pour rendre un script débogueurable. La classe d’implémentation de l’interface IDataModelScript doit QueryInterface pour IDataModelScriptDebug si le script est débogueur. |
| IDataModelScriptDebugClient | L’interface utilisateur qui souhaite fournir la fonctionnalité de débogage de script implémente l’interface IDataModelScriptDebugClient. Le fournisseur de scripts utilise cette interface pour transmettre des informations de débogage de retour et de sortie (par exemple, les événements qui se produisent, les points d’arrêt, etc.) |
| IDataModelScriptDebugStack | Le fournisseur de scripts implémente cette interface pour exposer la notion de pile d’appels au débogueur de script. |
| IDataModelScriptDebugStackFrame | Le fournisseur de scripts implémente cette interface pour exposer la notion d’une trame de pile particulière dans la pile des appels. |
| IDataModelScriptDebugVariableSetEnumerator | Le fournisseur de scripts implémente cette interface pour exposer un ensemble de variables. Cet ensemble peut représenter l’ensemble de paramètres d’une fonction, l’ensemble de variables locales ou l’ensemble de variables dans une étendue particulière. La signification exacte dépend de la façon dont l’interface a été acquise. |
| IDataModelScriptDebugBreakpoint | Le fournisseur de scripts implémente cette interface pour exposer la notion et le contrôle d’un point d’arrêt particulier dans le script. |
| IDataModelScriptDebugBreakpointEnumerator | Le fournisseur de scripts implémente ceci pour énumérer tous les points d’arrêt qui existent actuellement dans le script (activés ou non). |
Les interfaces de gestion générales sont les suivantes :
| Interface | Description |
|---|---|
| IDataModelScriptProvider | Interface principale qu’un fournisseur de scripts doit implémenter. Il s’agit de l’interface qui est inscrite auprès de la partie gestionnaire de scripts du gestionnaire de modèles de données afin de publier la prise en charge du fournisseur d’un type particulier de script et de s’inscrire auprès d’une extension de fichier particulière |
| IDataModelScript | Abstraction d’un script particulier géré par le fournisseur. Chaque script chargé ou en cours de modification a une instance IDataModelScript distincte |
| IDataModelScriptClient | Interface cliente utilisée par le fournisseur de scripts pour communiquer des informations à une interface utilisateur. Les fournisseurs de script n’implémentent pas cette interface. L’application hébergeant le modèle de données qui souhaite utiliser des fournisseurs de script. Un fournisseur de scripts appelle les méthodes du client de script pour signaler l’état, les erreurs, etc. |
| IDataModelScriptHostContext | Interface hôte utilisée par le fournisseur de scripts comme conteneur pour le contenu du script. Comment le contenu d’une surface de script autre que les manipulations qu’il effectue sur le modèle objet de l’application de débogueur est jusqu’à l’hôte de débogage particulier. Cette interface permet au fournisseur de scripts d’obtenir des informations sur l’emplacement où placer son contenu. |
| IDataModelScriptTemplate | Les fournisseurs de scripts peuvent fournir un ou plusieurs modèles qui servent de points de départ aux utilisateurs pour créer des scripts. Une application de débogueur qui fournit un éditeur intégré peut préremplir de nouveaux scripts avec du contenu de modèle tel qu’annoncé par le fournisseur via cette interface. |
| IDataModelScriptTemplateEnumerator | Interface d’énumérateur que le fournisseur de scripts implémente afin de publier tous les différents modèles qu’il prend en charge. |
| IDataModelNameBinder | Classeur de noms : objet qui peut associer un nom dans un contexte à une valeur. Pour une expression donnée telle que « foo.bar », un classeur de noms peut lier le nom « bar » dans le contexte de l’objet « foo » et produire une valeur ou une référence à celui-ci. Les classeurs de noms ne sont généralement pas implémentés par un fournisseur de scripts ; au lieu de cela, le classeur par défaut peut être acquis à partir du modèle de données et utilisé par le fournisseur de scripts. |
Création de scripts débogueur : IDataModelScriptDebug
Tout script débogueur indique cette fonctionnalité via la présence de l’interface IDataModelScriptDebug sur le même composant qui implémente IDataModelScript. La requête de cette interface par l’hôte de débogage ou l’application de débogueur hébergeant le modèle de données est ce qui indique la présence de la fonctionnalité de débogage.
L’interface IDataModelScriptDebug est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptDebug, IUnknown)
{
STDMETHOD_(ScriptDebugState, GetDebugState)() PURE;
STDMETHOD(GetCurrentPosition)(_Out_ ScriptDebugPosition *currentPosition, _Out_opt_ ScriptDebugPosition *positionSpanEnd, _Out_opt_ BSTR *lineText) PURE;
STDMETHOD(GetStack)(_COM_Outptr_ IDataModelScriptDebugStack **stack) PURE;
STDMETHOD(SetBreakpoint)(_In_ ULONG linePosition, _In_ ULONG columnPosition, _COM_Outptr_ IDataModelScriptDebugBreakpoint **breakpoint) PURE;
STDMETHOD(FindBreakpointById)(_In_ ULONG64 breakpointId, _COM_Outptr_ IDataModelScriptDebugBreakpoint **breakpoint) PURE;
STDMETHOD(EnumerateBreakpoints)(_COM_Outptr_ IDataModelScriptDebugBreakpointEnumerator **breakpointEnum) PURE;
STDMETHOD(GetEventFilter)(_In_ ScriptDebugEventFilter eventFilter, _Out_ bool *isBreakEnabled) PURE;
STDMETHOD(SetEventFilter)(_In_ ScriptDebugEventFilter eventFilter, _In_ bool isBreakEnabled) PURE;
STDMETHOD(StartDebugging)(_In_ IDataModelScriptDebugClient *debugClient) PURE;
STDMETHOD(StopDebugging)(_In_ IDataModelScriptDebugClient *debugClient) PURE;
}
La méthode GetDebugState retourne l’état actuel du script (par exemple, qu’il s’exécute ou non). L’état est défini par une valeur dans l’énumération ScriptDebugState.
La méthode GetCurrentPosition retourne la position actuelle dans le script. Cela peut uniquement être appelé lorsque le script est divisé en débogueur où un appel à GetScriptState retourne ScriptDebugBreak. Tout autre appel à cette méthode n’est pas valide et échoue.
La méthode GetStack obtient la pile des appels actuelle à la position d’arrêt. Cette méthode peut uniquement être appelée lorsque le script est divisé en débogueur.
La méthode SetBreakpoint définit un point d’arrêt dans le script. Notez que l’implémentation est libre d’ajuster les positions de ligne et de colonne insérées pour passer à une position de code appropriée. Les numéros de ligne et de colonne réels où le point d’arrêt a été placé peuvent être récupérés par des appels de méthode sur l’interface IDataModelScriptDebugBreakpoint retournée.
Chaque point d’arrêt créé dans le script via la méthode SetBreakpoint reçoit un identificateur unique (entier non signé 64 bits) par l’implémentation. La méthode FindBreakpointById est utilisée pour obtenir une interface vers le point d’arrêt à partir d’un identificateur donné.
Énumérer les points de terminaison
La méthode EnumerateBreakpoints retourne un énumérateur capable d’énumérer chaque point d’arrêt défini dans un script particulier.
La méthode GetEventFilter retourne si l’option « break on event » est activée pour un événement particulier. Les événements qui peuvent entraîner un « arrêt sur l’événement » sont décrits par un membre de l’énumération ScriptDebugEventFilter.
La méthode SetEventFilter modifie le comportement « break on event » pour un événement particulier tel que défini par un membre de l’énumération ScriptDebugEventFilter. Vous trouverez la liste complète des événements disponibles (et une description de cette énumération) dans la documentation de la méthode GetEventFilter.
La méthode StartDebugging « active » le débogueur pour un script particulier. L’acte de démarrage du débogage n’entraîne pas activement un saut d’exécution ou un pas à pas. Il rend simplement le script débogueurable et fournit un ensemble d’interfaces pour que le client communique avec l’interface de débogage.
La méthode StopDebugging est appelée par un client qui souhaite arrêter le débogage. Cet appel de méthode peut être effectué à tout moment après l’exécution de StartDebugging (par exemple, lors d’un arrêt, pendant l’exécution du script, etc.). L’appel cesse immédiatement toute activité de débogage et réinitialise l’état avant l’appel de StartDebugging.
l’interface de débogage : IDataModelScriptDebugClient
L’hôte de débogage ou l’application de débogueur qui souhaite fournir une interface autour du débogage de script doit fournir une implémentation de l’interface IDataModelScriptDebugClient au débogueur de script via la méthode StartDebugging sur l’interface de débogage du script.
IDataModelScriptDebugClient est le canal de communication sur lequel les événements de débogage sont passés et le contrôle passe du moteur d’exécution de script à une interface de débogueur. Elle est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptDebugClient, IUnknown)
{
STDMETHOD(NotifyDebugEvent)(_In_ ScriptDebugEventInformation *pEventInfo, _In_ IDataModelScript *pScript, _In_opt_ IModelObject *pEventDataObject, _Inout_ ScriptExecutionKind *resumeEventKind) PURE;
}
Chaque fois qu’un événement se produit qui se décompose dans le débogueur de script, le code de débogage lui-même effectue un appel à l’interface via la méthode NotifyDebugEvent. Cette méthode est synchrone. Aucune exécution du script ne reprend jusqu’à ce que l’interface retourne de l’événement. La définition du débogueur de script est destinée à être simple : il n’existe absolument aucun événement imbriqué nécessitant un traitement. Un événement de débogage est défini par un enregistrement variant appelé ScriptDebugEventInformation. Les champs dans les informations d’événement valides sont largement définis par le membre DebugEvent. Il définit le type d’événement qui s’est produit comme décrit par un membre de l’énumération ScriptDebugEvent.
La pile des appels : IDataModelScriptDebugStack
Lorsqu’un événement se produit qui se décompose dans le débogueur de script, l’interface de débogage souhaite récupérer la pile des appels pour l’emplacement d’arrêt. Cette opération est effectuée via la méthode GetStack. Cette pile est exprimée via IDataModelScriptDebugStack, qui est définie comme indiqué ci-dessous.
Notez que la pile globale peut s’étendre sur plusieurs scripts et/ou plusieurs fournisseurs de scripts. La pile d’appels retournée à partir d’un seul appel à la méthode GetStack sur l’interface de débogage d’un script particulier doit uniquement retourner le segment de la pile des appels dans les limites de ce script. Il est tout à fait possible qu’un moteur de débogage de script puisse récupérer la pile des appels comme s’étend sur plusieurs contextes de script si deux scripts du même fournisseur interagissent. La méthode GetStack ne doit pas retourner la partie de la pile qui se trouve dans un autre script. Au lieu de cela, si cette situation peut être détectée, l’image de pile qui est le cadre de limite dans le script doit se marquer comme une trame de transition via une implémentation des méthodes IsTransitionPoint et GetTransition sur cette trame de pile. On s’attend à ce que l’interface du débogueur rassemble la pile globale à partir des segments de pile multiples qui existent.
Il est impératif que les transitions soient implémentées de cette manière ou que l’interface de débogage puisse diriger des recherches sur les variables locales, les paramètres, les points d’arrêt et d’autres constructions spécifiques de script au contexte de script incorrect ! Cela entraîne un comportement non défini dans l’interface du débogueur.
DECLARE_INTERFACE_(IDataModelScriptDebugStack, IUnknown)
{
STDMETHOD_(ULONG64, GetFrameCount)() PURE;
STDMETHOD(GetStackFrame)(_In_ ULONG64 frameNumber, _COM_Outptr_ IDataModelScriptDebugStackFrame **stackFrame) PURE;
}
La méthode GetFrameCount retourne le nombre d’images de pile dans ce segment de la pile des appels. Si le fournisseur peut détecter des trames dans différents contextes de script ou de différents fournisseurs, il doit indiquer cela à l’appelant en implémentation des méthodes IsTransitionPoint et GetTransition sur l’image d’entrée dans ce segment de pile.
GetStackFrame obtient une trame de pile particulière à partir du segment de pile. La pile des appels a un système d’indexation de base zéro : le frame de pile actuel où l’événement d’arrêt s’est produit est l’image 0. L’appelant de la méthode actuelle est l’image 1 (et ainsi de suite).
'état d’examen lorsqu’il est rompu : IDataModelScriptDebugStackFrame
Une trame particulière de la pile des appels lorsqu’elle est divisée dans le débogueur de script peut être récupérée via un appel à la méthode GetStackFrame sur l’interface IDataModelScriptDebugStack représentant le segment de pile où l’arrêt s’est produit. L’interface IDataModelScriptDebugStackFrame retournée pour représenter ce frame est définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptDebugStackFrame, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *name) PURE;
STDMETHOD(GetPosition)(_Out_ ScriptDebugPosition *position, _Out_opt_ ScriptDebugPosition *positionSpanEnd, _Out_opt_ BSTR *lineText) PURE;
STDMETHOD(IsTransitionPoint)(_Out_ bool *isTransitionPoint) PURE;
STDMETHOD(GetTransition)(_COM_Outptr_ IDataModelScript **transitionScript, _Out_ bool *isTransitionContiguous) PURE;
STDMETHOD(Evaluate)(_In_ PCWSTR pwszExpression, _COM_Outptr_ IModelObject **ppResult) PURE;
STDMETHOD(EnumerateLocals)(_COM_Outptr_ IDataModelScriptDebugVariableSetEnumerator **variablesEnum) PURE;
STDMETHOD(EnumerateArguments)(_COM_Outptr_ IDataModelScriptDebugVariableSetEnumerator **variablesEnum) PURE;
}
La méthode GetName retourne le nom complet (par exemple : nom de fonction) de ce frame. Ce nom s’affiche dans le backtrac de la pile présenté à l’utilisateur dans l’interface du débogueur.
La méthode GetPosition retourne la position dans le script représenté par le frame de pile. Cette méthode peut uniquement être appelée lorsque le script se trouve dans un saut représenté par la pile dans laquelle cette trame est contenue. La position de ligne et de colonne dans ce cadre est toujours retournée. Si le débogueur est capable de retourner l’étendue de la « position d’exécution » dans le script, une position de fin peut être retournée dans l’argument positionSpanEnd. Si le débogueur n’est pas capable de cela, les valeurs de ligne et de colonne de l’étendue (si demandé) doivent être définies sur zéro.
L’interface IDataModelScriptDebugStack représente un segment d’une pile d’appels : cette partie de la pile des appels contenue dans le contexte d’un script. Si le débogueur est capable de détecter la transition d’un script à un autre (ou d’un fournisseur de scripts à un autre), il peut indiquer cela en implémentant la méthode IsTransitionPoint et en retournant true ou false selon les besoins. Trame de pile d’appels qui a entré le script où le segment s’applique doit être considéré comme un point de transition. Toutes les autres images ne sont pas.
Si une trame de pile donnée est un point de transition tel que déterminé par la méthode IsTransition (consultez la documentation relative à une définition de points de transition), la méthode GetTransition retourne des informations sur la transition. En particulier, cette méthode retourne le script précédent : celui qui a effectué un appel au script représenté par le segment de pile contenant ce IDataModelScriptDebugStackFrame.
La méthode Evaluate évalue une expression (du langage du fournisseur de scripts) dans le contexte de l’image de pile représentée par l’interface IDataModelScriptDebugStackFrame sur laquelle cette méthode a été appelée. Le résultat de l’évaluation de l’expression doit être marshalé hors du fournisseur de scripts en tant qu’IModelObject. Les propriétés et autres constructions sur le IModelObject résultant doivent tous être acquis pendant que le débogueur est dans un état d’arrêt.
La méthode EnumerateLocals retourne un jeu de variables (représenté par une interface IDataModelScriptDebugVariableSetEnumerator) pour toutes les variables locales qui sont dans l’étendue dans le contexte de l’image de pile représentée par l’interface IDataModelScriptDebugStackFrame sur laquelle cette méthode a été appelée.
La méthode EnumerateArguments retourne un jeu de variables (représenté par une interface IDataModelScriptDebugVariableSetEnumerator) pour tous les arguments de fonction de la fonction appelées dans le frame de pile représenté par l’interface IDataModelScriptDebugStackFrame sur laquelle cette méthode a été appelée.
Examiner les variables : IDataModelScriptDebugVariableSetEnumerator
Un ensemble de variables dans le script en cours de débogage (qu’elles soient dans une étendue particulière, les variables locales d’une fonction, les arguments d’une fonction, etc.) sont représentées par un jeu de variables défini via l’interface IDataModelScriptDebugVariableSetEnumerator :
DECLARE_INTERFACE_(IDataModelScriptDebugVariableSetEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_ BSTR *variableName, _COM_Outptr_opt_ IModelObject **variableValue, _COM_Outptr_opt_result_maybenull_ IKeyStore **variableMetadata) PURE;
}
La méthode Reset réinitialise la position de l’énumérateur à l’emplacement où elle était immédiatement après la création, autrement dit, avant le premier élément du jeu.
La méthode GetNext déplace l’énumérateur vers la variable suivante dans l’ensemble et retourne le nom, la valeur et toutes les métadonnées associées à cette variable. Si l’énumérateur a atteint la fin du jeu, l’erreur E_BOUNDS est retournée. Une fois que le marqueur E_BOUNDS a été retourné à partir de la méthode GetNext, il continue à produire E_BOUNDS lorsqu’il est appelé à nouveau, sauf si un appel de réinitialisation intermédiaire est effectué.
points d’arrêt : IDataModelScriptDebugBreakpoint
Les points d’arrêt de script sont définis via la méthode SetBreakpoint sur l’interface de débogage d’un script donné. Ces points d’arrêt sont représentés à la fois par un ID unique et une implémentation de l’interface IDataModelScriptDebugBreakpoint définie comme suit.
DECLARE_INTERFACE_(IDataModelScriptDebugBreakpoint, IUnknown)
{
STDMETHOD_(ULONG64, GetId)() PURE;
STDMETHOD_(bool, IsEnabled)() PURE;
STDMETHOD_(void, Enable)() PURE;
STDMETHOD_(void, Disable)() PURE;
STDMETHOD_(void, Remove)() PURE;
STDMETHOD(GetPosition)(_Out_ ScriptDebugPosition *position, _Out_opt_ ScriptDebugPosition *positionSpanEnd, _Out_opt_ BSTR *lineText) PURE;
}
La méthode GetId retourne l’identificateur unique attribué par le moteur de débogage du fournisseur de scripts au point d’arrêt. Cet identificateur doit être unique dans le contexte du script conteneur. L’identificateur de point d’arrêt peut être unique au fournisseur ; toutefois, cela n’est pas obligatoire.
La méthode IsEnabled retourne si le point d’arrêt est activé ou non. Un point d’arrêt désactivé existe toujours et se trouve toujours dans la liste des points d’arrêt pour le script, il est simplement « désactivé » temporairement. Tous les points d’arrêt doivent être créés dans l’état activé.
La méthode Enable active le point d’arrêt. Si le point d’arrêt a été désactivé, « appuyez sur le point d’arrêt » après avoir appelé cette méthode entraîne un saut dans le débogueur.
La méthode Disable désactive le point d’arrêt. Après cet appel, « atteindre le point d’arrêt » après l’appel de cette méthode ne se décompose pas dans le débogueur. Le point d’arrêt, tout en restant présent, est considéré comme « désactivé ».
La méthode Remove supprime le point d’arrêt de sa liste contenante. Le point d’arrêt n’existe plus sémantiquement une fois cette méthode retournée. L’interface IDataModelScriptDebugBreakpoint qui a représenté le point d’arrêt est considérée comme orpheline après l’appel. Rien d’autre ne peut (légalement) être fait avec lui après cet appel autre que de le libérer.
La méthode GetPosition retourne la position du point d’arrêt dans le script. Le débogueur de script doit retourner la ligne et la colonne dans le code source où se trouve le point d’arrêt. S’il est capable de le faire, il peut également retourner une étendue de source représentée par le point d’arrêt en remplissant une position de fin telle que définie par l’argument positionSpanEnd. Si le débogueur n’est pas en mesure de produire cette étendue et que l’appelant le demande, les champs Ligne et Colonne de la position de fin de l’étendue doivent être renseignés comme zéro indiquant que les valeurs ne peuvent pas être fournies.
énumération de point d’arrêt : IDataModelScriptDebugBreakpointEnumerator
Si un fournisseur de scripts prend en charge le débogage, il doit également suivre tous les points d’arrêt associés à chaque script et être capable d’énumérer ces points d’arrêt à l’interface de débogage. L’énumérateur pour les points d’arrêt est acquis via la méthode EnumerateBreakpoints sur l’interface de débogage d’un script donné et est défini comme suit.
DECLARE_INTERFACE_(IDataModelScriptDebugBreakpointEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptDebugBreakpoint **breakpoint) PURE;
}
La méthode Reset réinitialise la position de l’énumérateur à l’emplacement où elle s’est déroulée juste après la création de l’énumérateur, c’est-à-dire avant le premier point d’arrêt énuméré.
La méthode GetNext déplace l’énumérateur vers le point d’arrêt suivant à énumérer et retourne l’interface IDataModelScriptDebugBreakpoint pour ce point d’arrêt. Si l’énumérateur a atteint la fin de l’énumération, il retourne E_BOUNDS. Une fois l’erreur E_BOUNDS générée, les appels suivants à la méthode GetNext continueront de produire E_BOUNDS, sauf si un appel intermédiaire à la méthode Reset a été effectué.
Voir aussi
Cette rubrique fait partie d’une série qui décrit les interfaces accessibles à partir de C++, comment les utiliser pour générer 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 du débogueur C++
interfaces C++ du modèle de données du débogueur
objets C++ du modèle de données du débogueur
modèle de données du débogueur C++ interfaces supplémentaires