Script C++ du modèle de données du débogueur
Cette rubrique explique comment utiliser le script C++ du modèle de données débogueur 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
En plus du rôle du Gestionnaire de modèle de données en tant qu’autorité centrale sur la création d’objets et l’extensibilité, 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èle de données, un script peut être chargé, déchargé et potentiellement débogué dynamiquement par un fournisseur afin d’étendre ou de fournir de nouvelles fonctionnalités au modèle de données.
Un fournisseur de script est un composant qui relie un langage (par exemple, NatVis, JavaScript, etc.) au modèle de données. Il enregistre une ou plusieurs extensions de fichier (par exemple , ). NatVis », « .js ») qui sont gérés par le fournisseur, ce qui permet à 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.
Gestionnaire de scripts principal : IDataModelScriptManager
L’interface du gestionnaire de scripts de base 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 instance, étant donné l’expression « foo.bar », un classeur de noms est appelé pour résoudre la barre de noms dans le contexte de l’objet foo. Le classeur retourné ici suit un ensemble de règles par défaut pour le modèle de données. Les fournisseurs de scripts peuvent utiliser ce classeur pour fournir une cohérence dans la résolution de noms entre les fournisseurs.
La méthode RegisterScriptProvider informe le modèle de données qu’il existe un nouveau fournisseur de script capable de relier un nouveau langage au modèle de données. Lorsque cette méthode est appelée, le gestionnaire de scripts rappelle immédiatement le fournisseur de script donné et se renseigne 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 indiqué par le fournisseur de script donné, cette méthode échoue. Un seul fournisseur de script 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 lui seront plus associés. Il est important de noter qu’il peut y avoir un nombre important de références COM en attente au fournisseur de script, 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 script donné gère. Si un script chargé par ce fournisseur est toujours chargé ou a manipulé le modèle objet du débogueur (ou du 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 script doit être prêt à traiter ce problème.
La méthode FindProviderForScriptType recherche dans le gestionnaire de scripts un fournisseur qui a une chaîne de type script, comme indiqué dans cette méthode. S’il est introuvable, cette méthode échoue ; dans le cas contraire, ce fournisseur de script sera retourné à l’appelant.
La méthode EnumerateScriptProviders retourne un énumérateur qui énumère chaque fournisseur de script qui a été 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 au format suivant :
DECLARE_INTERFACE_(IDataModelScriptProviderEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptProvider **provider) PURE;
}
La méthode Reset déplace l’énumérateur à la position à laquelle il se trouvait avant de retourner le premier élément.
La méthode GetNext déplace l’énumérateur vers l’avant d’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 continue à retourner E_BOUNDS indéfiniment.
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 les scripts
L’hôte de débogage expose une série d’interfaces de très bas niveau pour comprendre la nature du système de type de ses cibles de débogage, évaluer des expressions dans le langage de sa ou ses cibles de débogage, etc... Normalement, il n’est pas concerné par les constructions de niveau supérieur comme les scripts. Cela est laissé à l’application de débogueur globale ou aux extensions qui fournissent ces fonctionnalités. Il y a toutefois une exception à cela. Tout hôte de débogage qui souhaite participer à l’expérience de script globale 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 les autres fonctionnalités fournies par le script dans l’espace de noms du modèle de données. Le fait d’être impliqué dans ce processus permet à l’hôte d’autoriser (ou non) l’utilisation de telles fonctions dans, pour instance, 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 de l’emplacement des objets. |
| IDataModelScriptHostContext | Interface hôte qui est utilisée par le fournisseur de script comme conteneur pour le contenu du script. Comment le contenu d’un script surface autre que les manipulations qu’il effectue sur le modèle objet de l’application débogueur est à la hauteur de l’hôte de débogage particulier. Cette interface permet au fournisseur de script d’obtenir des informations sur l’emplacement de son contenu. Pour plus d’informations, consultez Interfaces de script C++ du modèle de données plus loin dans cette rubrique. |
Hôte de script de l’hôte de débogage : IDebugHostScriptHost
L’interface IDebugHostScriptHost est l’interface utilisée par un fournisseur de script 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 script peut placer des ponts entre le modèle de données et l’environnement de script. Ces ponts peuvent, pour instance, ê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 à l’aide de 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 script 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
Interfaces de script et de script
L’architecture globale du modèle de données permet à un tiers de définir un pont entre un langage et le modèle objet du modèle de données. En règle générale, le langage faisant l’objet d’un pontage 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. Lors de l’initialisation, un fournisseur de script s’inscrit auprès de la partie gestionnaire de scripts du gestionnaire de modèles de données et toute interface qui gère l’extensibilité permet par la suite d’éditer, de charger, de décharger et éventuellement de déboguer des scripts écrits dans le langage que le fournisseur de script 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 des ponts entre les modèles XML NatVis 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 fait le pont entre les scripts écrits en 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 pour relier d’autres langages (par exemple, Python, etc.) au modèle de données. Celles-ci seraient actuellement encapsulées dans des 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 n’utiliser les API de modèle de données que si possible. Cela permettra au fournisseur d’être rendu portable à 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 concerne la gestion générale des fournisseurs de scripts et des scripts qu’ils gèrent. La deuxième classe d’interfaces concerne la prise en charge du débogage de script. Bien que la prise en charge du premier ensemble soit obligatoire, la prise en charge du second est facultative et peut ne pas avoir de sens pour tous les fournisseurs.
Les interfaces de gestion générale sont les suivantes :
| Interface | Description |
|---|---|
| IDataModelScriptProvider | Interface principale qu’un fournisseur de script 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 par le 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 un IDataModelScript distinct instance |
| IDataModelScriptClient | Interface cliente utilisée par le fournisseur de script 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 le fait. Un fournisseur de script appelle les méthodes du client de script pour signaler les status, les erreurs, etc. |
| IDataModelScriptHostContext | Interface hôte qui est utilisée par le fournisseur de script comme conteneur pour le contenu du script. Comment le contenu d’un script surface autre que les manipulations qu’il effectue sur le modèle objet de l’application débogueur est à la hauteur de l’hôte de débogage particulier. Cette interface permet au fournisseur de script d’obtenir des informations sur l’emplacement de son contenu. |
| IDataModelScriptTemplate | Les fournisseurs de script 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 comme annoncé par le fournisseur via cette interface. |
| IDataModelScriptTemplateEnumerator | Interface d’énumérateur que le fournisseur de script implémente pour 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 script ; 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 script |
Les interfaces de débogage sont les suivantes :
| Interface | Description |
|---|---|
| IDataModelScriptDebug | Interface principale qu’un fournisseur de script doit fournir pour qu’un script soit débogué. La classe d’implémentation de l’interface IDataModelScript doit QueryInterface pour IDataModelScriptDebug si le script peut être débogué. |
| IDataModelScriptDebugClient | L’interface utilisateur qui souhaite fournir la fonctionnalité de débogage de script implémente l’interface IDataModelScriptDebugClient. Le fournisseur de script utilise cette interface pour transmettre les informations de débogage (par exemple, les événements qui se produisent, les points d’arrêt, etc.) |
| IDataModelScriptDebugStack | Le fournisseur de script implémente cette interface pour exposer la notion de pile d’appels au débogueur de script. |
| IDataModelScriptDebugStackFrame | Le fournisseur de script implémente cette interface pour exposer la notion d’une trame de pile particulière dans la pile des appels. |
| IDataModelScriptDebugVariableSetEnumerator | Le fournisseur de script 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 script 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 script implémente ceci pour énumérer tous les points d’arrêt qui existent actuellement dans le script (activés ou non). |
Fournisseur de script principal : IDataModelScriptProvider
Toute extension qui souhaite être un fournisseur de script 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 de la langue 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. Voici quelques exemples de chaînes qui peuvent être retournées à partir de cette méthode : « JavaScript » ou « NatVis ». La chaîne retournée apparaît probablement dans l’interface utilisateur de l’application de débogueur qui héberge le modèle de données. Deux fournisseurs de script ne peuvent pas retourner le même nom (ne respectant pas la casse).
La méthode GetExtension retourne l’extension de fichier pour les scripts gérés par ce fournisseur (sans le point) sous la forme d’une chaîne allouée via la méthode SysAllocString. L’application de débogueur hébergeant le modèle de données (avec prise en charge des scripts) déléguera l’ouverture des fichiers de script avec cette extension au fournisseur de script. L’appelant est chargé de libérer la chaîne retournée via SysFreeString. Des 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 script 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 indépendamment du fait qu’une interface utilisateur crée un script vide à modifier par l’utilisateur ou que l’application débogueur charge un script à partir du disque. Le fournisseur n’est pas impliqué dans les E/S de fichiers. 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 de modèle par défaut du fournisseur. Il s’agit du contenu que le fournisseur de script souhaite préremplie dans une fenêtre d’édition pour un script nouvellement créé. Si le fournisseur de script n’a aucun modèle (ou n’a pas de contenu de modèle désigné comme contenu par défaut), le fournisseur de script peut retourner E_NOTIMPL à partir de cette méthode.
La méthode EnumerateTemplates retourne un énumérateur capable d’énumérer la variété des modèles fournis par le fournisseur de script. Le contenu du modèle est ce que le fournisseur de script souhaite être « prérempli » dans une fenêtre d’édition lors de la création d’un script. S’il existe plusieurs modèles différents 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.
Interface de script principale : IDataModelScript
L’interface main 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’avoir un impact sur un autre script, sauf via une interaction explicite avec des objets externes via le modèle de données. Deux scripts, peuvent pour instance, tous deux étendre un type ou un concept (par exemple, la notion du débogueur de ce qu’est un processus). Les deux scripts peuvent ensuite accéder aux champs de l’autre 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 sous la forme d’une chaîne allouée via la fonction SysAllocString. Si le script n’a pas encore de nom, la méthode doit retourner un 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 lors de tout appel à la méthode GetName. Cela est souvent appelé lorsqu’une interface utilisateur choisit d’enregistrer en tant que le script vers 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 afin de modifier ou de synchroniser le « contenu » du script. Il s’agit de la notification envoyée au fournisseur de script indiquant 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 aux objets que le script manipule. Il s’agit simplement d’une notification au fournisseur de script indiquant 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 que 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 script) définit une « fonction main » (une fonction que l’auteur souhaiterait appeler en cliquant sur un bouton « Exécuter le script » imaginaire dans une interface utilisateur), une telle « fonction main » n’est pas appelée lors d’une opération d’exécution. L’opération d’exécution peut être considérée pour effectuer des manipulations d’initialisation et de modèle objet uniquement (par exemple, l’exécution du code racine et la configuration de points d’extensibilité).
La méthode Unlink annule l’opération Execute. Les manipulations de modèle objet ou les points d’extensibilité établis pendant l’exécution du script sont annulés. Après une opération Dissocier, 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 ou non, c’est-à-dire s’il a une « fonction main » telle que définie par son langage ou son fournisseur. Une telle « fonction main » est conceptuellement quelque chose que l’auteur de script souhaiterait appeler si un bouton imaginaire « Exécuter le script » était enfoncé dans une interface utilisateur.
Si le script a une « fonction main » destinée à s’exécuter à partir d’un appel d’interface utilisateur, il l’indique par le biais d’un vrai retour de la méthode IsInvocable. L’interface utilisateur peut ensuite appeler la méthode InvokeMain pour « appeler » le script. Notez que cela est différent de Execute qui exécute tout le code racine et établit un pont entre le script et 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 disposer d’une interface utilisateur (graphique ou console) autour de cette notion implémente l’interface IDataModelScriptClient. Cette interface est transmise à n’importe quel fournisseur de script pendant l’exécution ou l’appel ou à un script afin de transmettre les 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 script appelle la méthode ReportError pour notifier l’interface utilisateur de l’erreur.
Contexte hôte d’un script : IDataModelScriptHostContext
L’hôte de débogage a une certaine influence sur la façon et l’emplacement où il projette le contenu du script de modèle de données. Il est attendu que chaque script demande à l’hôte un contexte dans lequel placer des ponts vers le script (par exemple, des objets de fonction qui peuvent être appelés, etc...). Ce contexte est récupéré en appelant la méthode CreateContext sur IDebugHostScriptHost et en obtenant 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 script informe l’hôte de débogage de certaines opérations qui se produisent avec un appel de méthode à la méthode NotifyScriptChange dans 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 script peut placer des ponts entre le modèle de données et le script. C’est ici, par instance, que le fournisseur de script 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 de 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 script.
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 (le cas échéant) n’est pas obligatoire pour avoir un nom. Tous les autres modèles le 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 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. C’est ce qui serait prérempli dans la fenêtre d’édition si un utilisateur choisit 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 script peut fournir un ou plusieurs modèles qui pré-remplissent le contenu dans des scripts nouvellement créés dans une interface utilisateur. Si l’un de ces modèles est fourni, le fournisseur de script doit implémenter un énumérateur 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éfini 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 il se trouvait lors de sa première création, avant la création du premier modèle.
La méthode GetNext déplace l’énumérateur vers le modèle suivant et le 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 E_BOUNDS erreurs 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 ce que signifie la barre pour foo.bar) qui fonctionnera sur divers fournisseurs de script. 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 résolution du nom et la résolution des conflits lorsqu’un nom est défini plusieurs fois sur un objet. Certaines de ces règles incluent des éléments tels que la façon dont un nom projeté (ajouté par un modèle de données) se résout par rapport à un nom natif (un nom dans le système de type de la langue déboguée).
Afin d’assurer 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 au nom.
La méthode BindReference est similaire à BindValue en ce qu’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 tant que référence, le fournisseur de script peut utiliser la référence pour effectuer l’attribution de 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 méthodes EnumerateKeys, EnumerateValues et similaires sur IModelObject qui peuvent retourner plusieurs noms avec la même valeur (pour les classes de base, les modèles parents et autres), 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 que le coût de l’énumération d’un objet via le classeur de noms est beaucoup plus élevé que l’appel des méthodes IModelObject.
La méthode EnumerateReferences énumère l’ensemble de noms et fait référence à ceux-ci qui seront liés à l’objet selon les règles de la méthode BindReference. Contrairement aux méthodes EnumerateKeys, EnumerateValues et similaires sur IModelObject qui peuvent retourner plusieurs noms avec la même valeur (pour les classes de base, les modèles parents et autres), 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 que le coût de l’énumération d’un objet via le classeur de noms est beaucoup plus élevé que l’appel des méthodes IModelObject.
Interfaces de débogage de script C++ de modèle de débogueur
L’infrastructure des fournisseurs de script dans le modèle de données fournit également un concept autour du débogage des scripts. Tout script qui souhaite exposer des 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 faisant en sorte que des scripts déboguables implémentent l’interface IDataModelScriptDebug en plus de l’interface IDataModelScript. La présence de cette interface sur le script indique à l’infrastructure qu’elle peut être déboguée.
Bien que l’interface IDataModelScriptDebug soit le point de départ pour accéder aux fonctionnalités de débogage d’un fournisseur de script, 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 script doit fournir pour rendre un script débogueable. La classe d’implémentation de l’interface IDataModelScript doit QueryInterface pour IDataModelScriptDebug si le script est débogué. |
| IDataModelScriptDebugClient | L’interface utilisateur qui souhaite fournir la fonctionnalité de débogage de script implémente l’interface IDataModelScriptDebugClient. Le fournisseur de script utilise cette interface pour transmettre les informations de débogage (par exemple, les événements qui se produisent, les points d’arrêt, etc.) |
| IDataModelScriptDebugStack | Le fournisseur de script implémente cette interface pour exposer la notion de pile d’appels au débogueur de script. |
| IDataModelScriptDebugStackFrame | Le fournisseur de script implémente cette interface pour exposer la notion d’une trame de pile particulière dans la pile des appels. |
| IDataModelScriptDebugVariableSetEnumerator | Le fournisseur de script 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 script 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 script implémente ceci pour énumérer tous les points d’arrêt qui existent actuellement dans le script (qu’ils soient activés ou non). |
Les interfaces de gestion générale sont les suivantes :
| Interface | Description |
|---|---|
| IDataModelScriptProvider | Interface principale qu’un fournisseur de script doit implémenter. Il s’agit de l’interface inscrite auprès de la partie gestionnaire de scripts du gestionnaire de modèles de données afin de publier la prise en charge par le 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 un instance IDataModelScript distinct |
| IDataModelScriptClient | Interface cliente utilisée par le fournisseur de script 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 le fait. Un fournisseur de script appelle les méthodes du client de script pour signaler status, erreurs, etc... |
| IDataModelScriptHostContext | Interface hôte qui est utilisée par le fournisseur de script comme conteneur pour le contenu du script. La façon dont le contenu d’un script surface autre que les manipulations qu’il effectue sur le modèle objet de l’application de débogueur incombe à l’hôte de débogage particulier. Cette interface permet au fournisseur de script d’obtenir des informations sur l’emplacement de son contenu. |
| IDataModelScriptTemplate | Les fournisseurs de script peuvent fournir un ou plusieurs modèles qui servent de points de départ pour que les utilisateurs créent des scripts. Une application de débogueur qui fournit un éditeur intégré peut préremplir de nouveaux scripts avec le contenu du modèle tel qu’annoncé par le fournisseur via cette interface. |
| IDataModelScriptTemplateEnumerator | Interface énumératrice que le fournisseur de script implémente afin de publier tous les 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 est en mesure de lier le nom « bar » dans le contexte de l’objet « foo » et d’y produire une valeur ou une référence. Les classeurs de noms ne sont généralement pas implémentés par un fournisseur de script ; 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 script. |
Rendre les scripts débogueables : IDataModelScriptDebug
Tout script déboguable 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 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, s’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 ne peut être appelé que lorsque le script est décomposé dans le débogueur, où un appel à GetScriptState renvoie ScriptDebugBreak. Tout autre appel à cette méthode n’est pas valide et échoue.
La méthode GetStack obtient la pile d’appels actuelle à la position d’arrêt. Cette méthode ne peut être appelée que lorsque le script est rompu dans le 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 entrantes 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 se voit attribuer 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é.
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 indique si « break on event » est activé pour un événement particulier. Les événements qui peuvent provoquer une interruption de 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. Le fait de démarrer le débogage ne provoque pas activement d’interruption d’exécution ou de pas à pas. Il rend simplement le script débogueable et fournit un ensemble d’interfaces permettant au client de communiquer 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 la réussite de StartDebugging (par exemple, pendant une pause, pendant l’exécution du script, etc...).. L’appel cesse immédiatement toute activité de débogage et rétablit l’état avant l’appel de StartDebugging.
Interface de débogage : IDataModelScriptDebugClient
L’hôte de débogage ou l’application débogueur qui souhaite fournir une interface autour du débogage de script doit fournir une implémentation de l’interface IDataModelScriptDebugClient sur le débogueur de script via la méthode StartDebugging sur l’interface de débogage du script.
IDataModelScriptDebugClient est le canal de communication à travers 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. Il est défini comme suit.
DECLARE_INTERFACE_(IDataModelScriptDebugClient, IUnknown)
{
STDMETHOD(NotifyDebugEvent)(_In_ ScriptDebugEventInformation *pEventInfo, _In_ IDataModelScript *pScript, _In_opt_ IModelObject *pEventDataObject, _Inout_ ScriptExecutionKind *resumeEventKind) PURE;
}
Chaque fois que se produit un événement qui s’interrompt 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 reprendra tant que l’interface n’est pas retournée à partir de l’événement. La définition du débogueur de script est conçue pour être simple : il n’y a 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 qui sont valides sont en grande partie 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.
Pile des appels : IDataModelScriptDebugStack
Lorsqu’un événement se produit qui s’interrompt 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. Cela s’effectue via la méthode GetStack. Cette pile est exprimée via IDataModelScriptDebugStack qui est défini 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 ne doit retourner que le segment de la pile d’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 limite dans le script doit se marquer comme un cadre de transition via une implémentation des méthodes IsTransitionPoint et GetTransition sur ce cadre de pile. On s’attend à ce que l’interface du débogueur assemble la pile globale des plusieurs segments de pile qui existent.
Il est impératif que les transitions soient implémentées de cette manière ou l’interface de débogage peut diriger les demandes de renseignements sur les variables locales, les paramètres, les points d’arrêt et d’autres constructions spécifiques au script vers le 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 de trames de pile dans ce segment de la pile d’appels. Si le fournisseur peut détecter des trames dans différents contextes de script ou de fournisseurs différents, il doit l’indiquer à l’appelant en mettant en œuvre les méthodes IsTransitionPoint et GetTransition sur la trame d’entrée dans ce segment de pile.
GetStackFrame obtient une trame de pile particulière à partir du segment de pile. La pile d’appels a un système d’indexation de base zéro : l’image de pile actuelle 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).
Examen de l’état en cas de rupture : IDataModelScriptDebugStackFrame
Une trame particulière de la pile d’appels en cas de rupture 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 qui est 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 d’affichage (par exemple, nom de la fonction) de ce frame. Ce nom s’affiche dans le backtrace de 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 cadre de pile. Cette méthode ne peut être appelée que lorsque le script se trouve dans un saut représenté par la pile dans laquelle ce frame est contenu. La position de la ligne et de la 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’en est pas capable, les valeurs de ligne et de colonne à l’extrémité de l’étendue (si nécessaire) doivent être définies sur zéro.
L’interface IDataModelScriptDebugStack représente un segment d’une pile d’appels, c’est-à-dire la partie de la pile d’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 script à un autre), il peut l’indiquer en implémentant la méthode IsTransitionPoint et en retournant true ou false le cas échéant. L’image de pile d’appels qui a entré le script où le segment s’applique doit être considérée comme un point de transition. Toutes les autres images ne le sont pas.
Si un frame de pile donné est un point de transition déterminé par la méthode IsTransition (voir la documentation qui y est consacrée pour 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 script) 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 script en tant qu’IModelObject. Les propriétés et autres constructions du IModelObject résultant doivent tous pouvoir être acquis lorsque le débogueur est dans un état d’arrêt.
La méthode EnumerateLocals renvoie un jeu de variables (représenté par une interface IDataModelScriptDebugVariableSetEnumerator) pour toutes les variables locales qui sont dans l’étendue dans le contexte de la trame de pile représentée par l’interface IDataModelScriptDebugStackFrame sur laquelle cette méthode a été appelée.
La méthode EnumerateArguments retourne un ensemble de variables (représenté par une interface IDataModelScriptDebugVariableSetEnumerator) pour tous les arguments de fonction de la fonction appelée dans le frame de pile représenté par l’interface IDataModelScriptDebugStackFrame sur laquelle cette méthode a été appelée.
Analyse des variables : IDataModelScriptDebugVariableSetEnumerator
Un ensemble de variables dans le script en cours de débogage (qu’il s’agisse de celles d’une étendue particulière, des locaux d’une fonction, des arguments d’une fonction, etc...) est représenté 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ù il se trouvait immédiatement après sa création, c’est-à-dire avant le premier élément de l’ensemble.
La méthode GetNext déplace l’énumérateur vers la variable suivante dans l’ensemble et retourne le nom de la variable, sa valeur et toutes les métadonnées qui lui sont associées. 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 qui est 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 script au point d’arrêt. Cet identificateur doit être unique dans le contexte du script contenant. L’identificateur du point d’arrêt peut être propre 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 figure 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é, « l’atteinte du point d’arrêt » après l’appel de cette méthode entraîne une interruption 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 s’interrompt pas dans le débogueur. Le point d’arrêt, même s’il est toujours 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 après le retour de cette méthode. L’interface IDataModelScriptDebugBreakpoint qui représentait 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 elle 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, ce qui indique que les valeurs ne peuvent pas être fournies.
Énumération point d’arrêt : IDataModelScriptDebugBreakpointEnumerator
Si un fournisseur de script prend en charge le débogage, il doit également effectuer le suivi de tous les points d’arrêt associés à chaque script et être capable d’énumérer ces points d’arrêt dans 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 pour 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ù il se trouvait 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 l’avant 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 que l’erreur de E_BOUNDS a été générée, les appels suivants à la méthode GetNext continuent à 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 créer une extension de débogueur C++ et comment utiliser d’autres constructions de modèles 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 du modèle de données C++ 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