Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
In dit onderwerp wordt beschreven hoe u foutopsporingsprogrammagegevensmodel C++ foutopsporingsprogramma's gebruikt om automatisering te ondersteunen met de foutopsporingsprogramma-engine met behulp van scripts.
scriptbeheer in het gegevensmodel voor foutopsporing
Naast de rol van Data Model Manager als centrale autoriteit voor het maken en uitbreidbaar maken van objecten, is het ook verantwoordelijk voor het beheer van een abstract concept van scripts. Vanuit het perspectief van het scriptbeheergedeelte van het gegevensmodelbeheer is een script iets dat dynamisch kan worden geladen, verwijderd en mogelijk fouten kan worden opgespoord door een provider om het gegevensmodel uit te breiden of nieuwe functionaliteit te bieden.
Een scriptprovider is een onderdeel dat een taal overbrugt (bijvoorbeeld NatVis, JavaScript, enzovoort) naar het gegevensmodel. Het registreert een of meer bestandsextensies (bijvoorbeeld: ". NatVis", ".js") die worden verwerkt door de provider, waardoor een foutopsporingsprogrammaclient of een gebruikersinterface kan worden gebruikt voor het laden van scriptbestanden met die specifieke extensie door delegatie aan de provider.
Core Script Manager: IDataModelScriptManager
De core script manager-interface wordt als volgt gedefinieerd.
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;
}
De methode GetDefaultNameBinder retourneert de standaardscriptnaambinding van het gegevensmodel. Een naambinding is een onderdeel waarmee een naam wordt omgezet binnen de context van een object. Op basis van de expressie 'foo.bar' wordt bijvoorbeeld een naambinding aangeroepen om de naambalk op te lossen in de context van object-foo. De binder die hier wordt geretourneerd, volgt een set standaardregels voor het gegevensmodel. Scriptproviders kunnen deze binder gebruiken om consistentie in naamomzetting tussen providers te bieden.
De methode RegisterScriptProvider informeert het gegevensmodel dat er een nieuwe scriptprovider bestaat die een nieuwe taal kan overbruggen naar het gegevensmodel. Wanneer deze methode wordt aangeroepen, wordt de scriptbeheerder onmiddellijk de opgegeven scriptprovider aangeroepen en wordt u gevraagd naar de eigenschappen van de scripts die worden beheerd. Als er al een provider is geregistreerd onder de naam of bestandsextensie die de opgegeven scriptprovider aangeeft, mislukt deze methode. Slechts één scriptprovider kan worden geregistreerd als handler voor een bepaalde naam of bestandsextensie.
Met de methode UnregisterScriptProvider wordt een aanroep naar de methode RegisterScriptProvider ongedaan maken. De naam en bestandsextensie die door de inpassed scriptprovider worden opgegeven, worden er niet meer aan gekoppeld. Het is belangrijk te weten dat er mogelijk een aanzienlijk aantal openstaande COM-verwijzingen naar de scriptprovider is, zelfs na het ongedaan maken van de registratie. Deze methode voorkomt alleen het laden/maken van scripts van het type dat de opgegeven scriptprovider beheert. Als een script dat door die provider wordt geladen nog steeds wordt geladen of het objectmodel van het foutopsporingsprogramma (of het gegevensmodel) heeft gemanipuleerd, hebben deze bewerkingen mogelijk nog steeds verwijzingen naar het script. Er kunnen gegevensmodellen, methoden of objecten zijn die rechtstreeks verwijzen naar constructies in het script. Er moet een scriptprovider worden voorbereid om hiermee om te gaan.
Met de methode FindProviderForScriptType wordt in scriptbeheer gezocht naar een provider met een tekenreeks van het scripttype, zoals aangegeven in deze methode. Als er geen kan worden gevonden, mislukt deze methode; anders wordt deze scriptprovider teruggezet naar de aanroeper.
De methode EnumerateScriptProviders retourneert een enumerator die elke scriptprovider opsommen die is geregistreerd bij de scriptbeheerder via een voorafgaande aanroep van de Methode RegisterScriptProvider.
Opsomming scriptprovider: IDataModelScriptProviderEnumerator
De methode EnumerateScriptProviders retourneert een enumerator van het volgende formulier:
DECLARE_INTERFACE_(IDataModelScriptProviderEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptProvider **provider) PURE;
}
Met de methode Reset wordt de enumerator verplaatst naar de positie waarop deze zich bevond voordat het eerste element werd geretourneerd.
De GetNext-methode verplaatst de enumerator één element naar voren en retourneert de scriptprovider die zich in dat element bevindt. Wanneer de opsomming het einde van de opsomming bereikt, wordt E_BOUNDS geretourneerd. Als u de GetNext-methode aanroept nadat deze fout is ontvangen, blijft E_BOUNDS voor onbepaalde tijd worden geretourneerd.
Gegevensmodel C++ hostinterfaces voor foutopsporing
de rol van de host bij het uitvoeren van scripts
De host voor foutopsporing maakt een reeks zeer laag niveau-interfaces beschikbaar om inzicht te krijgen in de aard van het type systeem van de doel(en) voor foutopsporing, het evalueren van expressies in de taal van de doel(en) voor foutopsporing, enzovoort... Normaal gesproken is het niet betrokken bij constructies op een hoger niveau, zoals scripting. Dit wordt overgelaten aan de algemene foutopsporingsprogrammatoepassing of aan extensies die deze mogelijkheden bieden. Er is echter een uitzondering op dit. Elke foutopsporingshost die wil deelnemen aan de algehele scriptervaring die door het gegevensmodel wordt geboden, moet een aantal eenvoudige interfaces implementeren om contexten voor scripts te bieden. De host voor foutopsporing heeft in feite de controle over waar de scriptomgeving functies en andere door scripts geleverde functionaliteit in de naamruimte van het gegevensmodel plaatst. Door betrokken te zijn bij dit proces kan de host het gebruik van dergelijke functies toestaan (of niet) in bijvoorbeeld de expressie-evaluator. De interfaces die vanuit het perspectief van de host zijn betrokken, zijn:
| gebruikersinterface | Beschrijving |
|---|---|
| IDebugHostScriptHost | De interface die de mogelijkheid aangeeft van de foutopsporingshost om deel te nemen aan de scriptomgeving. Met deze interface kunt u contexten maken die scriptengines informeren over waar objecten moeten worden geplaatst. |
| IDataModelScriptHostContext | Een hostinterface die door de scriptprovider wordt gebruikt als een container voor de inhoud van het script. Hoe de inhoud van een scriptoppervlak anders is dan de manipulaties die het uitvoert voor het objectmodel van de foutopsporingsprogrammatoepassing, is aan de specifieke foutopsporingshost. Met deze interface kan de scriptprovider informatie ophalen over waar de inhoud ervan moet worden opgeslagen. Zie Data Model C++ Scripting Interfaces verderop in dit onderwerp voor meer informatie. |
de scripthost van de host voor foutopsporing: IDebugHostScriptHost
De IDebugHostScriptHost-interface is de interface die door een scriptprovider wordt gebruikt om een context op te halen van de host voor foutopsporing voor een nieuw gemaakt script. Deze context omvat een object (geleverd door de foutopsporingshost) waar de scriptprovider alle bruggen tussen het gegevensmodel en de scriptomgeving kan plaatsen. Dergelijke bruggen kunnen bijvoorbeeld methoden voor gegevensmodellen zijn die scriptfuncties aanroepen. Hierdoor kan een aanroeper aan de zijde van het gegevensmodel scriptmethoden aanroepen door gebruik te maken van de aanroepmethode op de IModelMethod-interface.
De IDebugHostScriptHost-interface wordt als volgt gedefinieerd.
DECLARE_INTERFACE_(IDebugHostScriptHost, IUnknown)
{
STDMETHOD(CreateContext)(_In_ IDataModelScript* script, _COM_Outptr_ IDataModelScriptHostContext** scriptContext) PURE;
}
De methode CreateContext wordt aangeroepen door een scriptprovider om een nieuwe context te maken waarin de inhoud van het script moet worden geplaatst. Deze context wordt vertegenwoordigd door de interface IDataModelScriptHostContext die in detail wordt beschreven op de pagina Data Model C++ Scripting Interfaces.
Gegevensmodel C++ scriptinterfaces voor foutopsporing
script- en scriptinterfaces
Met de algemene architectuur van het gegevensmodel kan een derde partij een brug definiëren tussen een bepaalde taal en het objectmodel van het gegevensmodel. Normaal gesproken is de taal die wordt overbrugd een scripttaal omdat de omgeving van het gegevensmodel zeer dynamisch is. Een onderdeel dat deze brug definieert en implementeert tussen een taal en het objectmodel van het gegevensmodel, wordt een scriptprovider genoemd. Wanneer een scriptprovider is geïnitialiseerd, registreert deze zich met het scriptbeheergedeelte van de gegevensmodelbeheerder en elke interface die de uitbreidbaarheid beheert, kan het bewerken, laden, lossen en mogelijk foutopsporing van scripts die zijn geschreven naar de taal die de scriptprovider beheert.
Houd er rekening mee dat hulpprogramma's voor foutopsporing voor Windows momenteel twee scriptproviders definieert.
- De NatVis-provider. Deze provider is ingesloten in DbgEng.dll en bruggen tussen NatVis XML en gegevensmodellen, waardoor visualisatie van systeemeigen/taalgegevenstypen mogelijk is.
- De JavaScript-provider. Deze provider bevindt zich in een verouderde foutopsporingsprogramma-extensie: JsProvider.dll. Het overbrugt tussen scripts die zijn geschreven in de JavaScript-taal en het gegevensmodel, waardoor willekeurige vormen van besturingselement voor foutopsporing en uitbreidbaarheid mogelijk zijn.
Er kunnen nieuwe providers worden geschreven die andere talen overbruggingen (bijvoorbeeld Python, enzovoort) naar het gegevensmodel. Dergelijke worden momenteel ingekapseld in verouderde foutopsporingsprogramma-extensies voor laaddoeleinden. De scriptprovider zelf moet de afhankelijkheid met verouderde engine-interfaces minimaliseren en mag waar mogelijk alleen gebruikmaken van de API's van het gegevensmodel. Hierdoor kan de provider met een aanzienlijk groter gemak draagbaar worden gemaakt naar andere omgevingen.
Er zijn twee klassen interfaces met betrekking tot scriptproviders. De eerste klasse interfaces is voor algemeen beheer van scriptproviders en de scripts die ze beheren. De tweede klasse interfaces is voor ondersteuning van scriptopsporing. Hoewel ondersteuning voor de eerste set verplicht is, is de ondersteuning voor de tweede optioneel en is deze mogelijk niet zinvol voor elke provider.
De algemene beheerinterfaces zijn:
| gebruikersinterface | Beschrijving |
|---|---|
| IDataModelScriptProvider | De kerninterface die een scriptprovider moet implementeren. Dit is de interface die is geregistreerd bij het scriptbeheergedeelte van de gegevensmodelbeheerder om de ondersteuning van de provider van een bepaald type script te adverteren en zich te registreren bij een bepaalde bestandsextensie |
| IDataModelScript | Een abstractie van een bepaald script dat wordt beheerd door de provider. Elk script dat wordt geladen of bewerkt, heeft een afzonderlijk IDataModelScript-exemplaar |
| IDataModelScriptClient | Een clientinterface die door de scriptprovider wordt gebruikt om informatie te communiceren met een gebruikersinterface. Scriptproviders implementeren deze interface niet. De toepassing die als host fungeert voor het gegevensmodel dat gebruik wil maken van scriptproviders. Een scriptprovider roept methoden van de scriptclient aan om de status, fouten, enzovoort te rapporteren... |
| IDataModelScriptHostContext | Een hostinterface die door de scriptprovider wordt gebruikt als een container voor de inhoud van het script. Hoe de inhoud van een scriptoppervlak anders is dan de manipulaties die het uitvoert voor het objectmodel van de foutopsporingsprogrammatoepassing, is aan de specifieke foutopsporingshost. Met deze interface kan de scriptprovider informatie ophalen over waar de inhoud ervan moet worden opgeslagen. |
| IDataModelScriptTemplate | Scriptproviders kunnen een of meer sjablonen bieden die fungeren als uitgangspunt voor gebruikers om scripts te schrijven. Een foutopsporingsprogrammatoepassing die een ingebouwde editor biedt, kan nieuwe scripts vooraf invullen met sjablooninhoud, zoals aangekondigd door de provider via deze interface. |
| IDataModelScriptTemplateEnumerator | Een enumerator-interface die door de scriptprovider wordt geïmplementeerd om alle verschillende sjablonen te adverteren die worden ondersteund. |
| IDataModelNameBinder | Een naambinding - een object dat een naam in een context kan koppelen aan een waarde. Voor een bepaalde expressie, zoals 'foo.bar', kan een naambinding de naambalk in de context van object 'foo' binden en een waarde of verwijzing naar het object produceren. Naambindingen worden doorgaans niet geïmplementeerd door een scriptprovider; in plaats daarvan kan de standaardbinding worden verkregen uit het gegevensmodel en worden gebruikt door de scriptprovider |
De foutopsporingsinterfaces zijn:
| gebruikersinterface | Beschrijving |
|---|---|
| IDataModelScriptDebug | De kerninterface die een scriptprovider moet bieden om een script foutopsporing mogelijk te maken. De implementatieklasse van de IDataModelScript-interface moet QueryInterface voor IDataModelScriptDebug zijn als het script foutopsporingsbaar is. |
| IDataModelScriptDebugClient | De gebruikersinterface die de mogelijkheid van scriptopsporing wil bieden, implementeert de interface IDataModelScriptDebugClient. De scriptprovider maakt gebruik van deze interface om foutopsporingsinformatie heen en weer door te geven (bijvoorbeeld gebeurtenissen die optreden, onderbrekingspunten, enzovoort...) |
| IDataModelScriptDebugStack | De scriptprovider implementeert deze interface om het concept van een aanroepstack beschikbaar te maken voor het foutopsporingsprogramma voor scripts. |
| IDataModelScriptDebugStackFrame | De scriptprovider implementeert deze interface om het concept van een bepaald stackframe in de aanroepstack beschikbaar te maken. |
| IDataModelScriptDebugVariableSetEnumerator | De scriptprovider implementeert deze interface om een set variabelen beschikbaar te maken. Deze set kan de set parameters vertegenwoordigen voor een functie, de set lokale variabelen of de set variabelen binnen een bepaald bereik. De exacte betekenis is afhankelijk van hoe de interface is verkregen. |
| IDataModelScriptDebugBreakpoint | De scriptprovider implementeert deze interface om het concept van en het beheer van een bepaald onderbrekingspunt in het script beschikbaar te maken. |
| IDataModelScriptDebugBreakpointEnumerator | De scriptprovider implementeert dit om alle onderbrekingspunten op te sommen die momenteel aanwezig zijn in het script (al dan niet ingeschakeld). |
Core Script Provider: IDataModelScriptProvider
Elke extensie die een scriptprovider wil zijn, moet een implementatie van de IDataModelScriptProvider-interface bieden en deze registreren bij het scriptbeheergedeelte van de gegevensmodelbeheerder via de methode RegisterScriptProvider. Deze kerninterface die als volgt moet worden geïmplementeerd.
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;
}
De Methode GetName retourneert de naam van het type (of taal van) scripts dat de provider beheert als een tekenreeks die is toegewezen via de SysAllocString-methode. De beller is verantwoordelijk voor het vrijmaken van de geretourneerde tekenreeks via SysFreeString. Voorbeelden van tekenreeksen die uit deze methode kunnen worden geretourneerd, zijn 'JavaScript' of 'NatVis'. De geretourneerde tekenreeks wordt waarschijnlijk weergegeven in de gebruikersinterface van de foutopsporingsprogrammatoepassing die als host fungeert voor het gegevensmodel. Er kunnen geen twee scriptproviders dezelfde naam retourneren (hoofdlettergevoelig).
De Methode GetExtension retourneert de bestandsextensie voor scripts die worden beheerd door deze provider (zonder de stip) als een tekenreeks die is toegewezen via de SysAllocString-methode. De foutopsporingsprogrammatoepassing die als host fungeert voor het gegevensmodel (met ondersteuning voor scripts) delegeert het openen van scriptbestanden met deze extensie aan de scriptprovider. De beller is verantwoordelijk voor het vrijmaken van de geretourneerde tekenreeks via SysFreeString. Voorbeelden van tekenreeksen die uit deze methode kunnen worden geretourneerd, zijn 'js' of 'NatVis'.
De Methode CreateScript wordt aangeroepen om een nieuw script te maken. De scriptprovider moet een nieuw en leeg script retourneren dat wordt vertegenwoordigd door de geretourneerde IDataModelScript-interface wanneer deze methode wordt aangeroepen. Houd er rekening mee dat deze methode wordt aangeroepen, ongeacht of een gebruikersinterface een nieuw leeg script maakt voor bewerking door de gebruiker of dat de foutopsporingsprogrammatoepassing een script vanaf de schijf laadt. De provider wordt niet betrokken bij bestand I/O. Het verwerkt alleen de aanvragen van de hostingtoepassing via streams die worden doorgegeven aan methoden in IDataModelScript.
De methode GetDefaultTemplateContent retourneert een interface voor de standaardsjablooninhoud van de provider. Dit is inhoud die de scriptprovider vooraf wil invullen in een bewerkingsvenster voor een nieuw gemaakt script. Als de scriptprovider geen sjablonen heeft (of geen sjablooninhoud heeft die als standaardinhoud is aangewezen), kan de scriptprovider E_NOTIMPL van deze methode retourneren.
De methode EnumerateTemplates retourneert een enumerator die de verschillende sjablonen kan inventariseren die door de scriptprovider worden geleverd. Sjablooninhoud is wat de scriptprovider 'vooraf ingevuld' wil worden in een bewerkingsvenster bij het maken van een nieuw script. Als er meerdere verschillende sjablonen worden ondersteund, kunnen deze sjablonen een naam krijgen (bijvoorbeeld 'Imperatief script', 'Extensiescript') en de foutopsporingsprogrammatoepassing die als host fungeert voor het gegevensmodel, kan kiezen hoe de 'sjablonen' aan de gebruiker moeten worden weergegeven.
Core Script Interface: IDataModelScript
De hoofdinterface waarmee een afzonderlijk script wordt beheerd dat door de provider wordt geïmplementeerd, is de IDataModelScript-interface. Een onderdeel dat deze interface implementeert, wordt geretourneerd wanneer de client een nieuw leeg script wil maken en de CreateScript-methode op IDataModelScriptProvider wil aanroepen.
Elk script dat door de provider wordt gemaakt, moet zich in een onafhankelijke silo bevindt. Eén script mag geen invloed hebben op een ander script, behalve via expliciete interactie met externe objecten via het gegevensmodel. Twee scripts kunnen bijvoorbeeld een bepaald type of concept uitbreiden (bijvoorbeeld het begrip van het foutopsporingsprogramma van wat een proces is). Beide scripts hebben vervolgens toegang tot elkaars velden via het externe procesobject.
De interface wordt als volgt gedefinieerd.
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;
}
De Methode GetName retourneert de naam van het script als een toegewezen tekenreeks via de functie SysAllocString. Als het script nog geen naam heeft, moet de methode een null BSTR retourneren. In dit geval mag het niet mislukken. Als de naam van het script expliciet wordt gewijzigd via een aanroep naar de methode Rename, moet de GetName-methode de zojuist toegewezen naam retourneren.
naam van wijzigen
Met de methode Naam wijzigen wordt een nieuwe naam aan het script toegewezen. Het is de verantwoordelijkheid van de script-implementatie om deze naam op te slaan en deze te retourneren bij elke aanroep van de Methode GetName. Dit wordt vaak aangeroepen wanneer een gebruikersinterface ervoor kiest om op te slaan als het script naar een nieuwe naam. Houd er rekening mee dat het wijzigen van de naam van het script van invloed kan zijn op waar de hostingtoepassing ervoor kiest om de inhoud van het script te projecteren.
De methode Vullen wordt door de client aangeroepen om de 'inhoud' van het script te wijzigen of te synchroniseren. Het is de melding die wordt gedaan bij de scriptprovider dat de code van het script is gewijzigd. Het is belangrijk te weten dat deze methode geen uitvoering van het script veroorzaakt of wijzigingen aan een van de objecten die door het script worden bewerkt. Dit is slechts een melding aan de scriptprovider dat de inhoud van het script is gewijzigd, zodat deze mogelijk een eigen interne status kan synchroniseren.
De execute-methode voert de inhoud van het script uit zoals bepaald door de laatste geslaagde aanroep Vullen en wijzigt het objectmodel van het foutopsporingsprogramma op basis van die inhoud. Als de taal (of de scriptprovider) een 'hoofdfunctie' definieert , een die de auteur zou willen aanroepen wanneer hij op een imaginaire knop Script uitvoeren in een gebruikersinterface klikt, wordt deze 'hoofdfunctie' niet aangeroepen tijdens een execute-bewerking. De execute-bewerking kan alleen worden beschouwd als initialisatie- en objectmodelbewerkingen (bijvoorbeeld het uitvoeren van basiscode en het instellen van uitbreidbaarheidspunten).
Met de methode Ontkoppelen wordt de bewerking Uitvoeren ongedaan maken. Objectmodelbewerkingen of uitbreidbaarheidspunten die zijn vastgesteld tijdens de uitvoering van het script, worden ongedaan gemaakt. Na een ontkoppelingsbewerking kan het script opnieuw worden uitgevoerd via een aanroep voor Uitvoeren of kan het worden vrijgegeven.
De IsInvocable-methode retourneert of het script wel of niet aanroepbaar is, dat wil gezegd, of het nu een 'hoofdfunctie' heeft zoals gedefinieerd in de taal of provider. Een dergelijke 'hoofdfunctie' is conceptueel iets dat de auteur van het script zou willen aanroepen als een imaginaire knop 'Script uitvoeren' werd ingedrukt in een gebruikersinterface.
Als het script een 'hoofdfunctie' heeft die is bedoeld om uit te voeren vanuit een aanroep van de gebruikersinterface, geeft dit aan via een true return van de IsInvocable-methode. De gebruikersinterface kan vervolgens de InvokeMain-methode aanroepen om het script daadwerkelijk aan te roepen. Houd er rekening mee dat dit verschilt van Execute die alle hoofdcode uitvoert en het script overbrugt naar de naamruimte van de onderliggende host.
**De scriptclient: iDataModelScriptClient **
Een toepassing die als host fungeert voor het gegevensmodel dat scripts wil beheren en een gebruikersinterface (of een grafische console) rond dit concept heeft, implementeert de IDataModelScriptClient-interface. Deze interface wordt tijdens het uitvoeren of aanroepen of een script doorgegeven aan een script om fout- en gebeurtenisgegevens door te geven aan de gebruikersinterface.
De IDataModelScriptClient-interface wordt als volgt gedefinieerd.
DECLARE_INTERFACE_(IDataModelScriptClient, IUnknown)
{
STDMETHOD(ReportError)(_In_ ErrorClass errClass, _In_ HRESULT hrFail, _In_opt_ PCWSTR message, _In_ ULONG line, _In_ ULONG position) PURE;
}
Als er een fout optreedt tijdens het uitvoeren of aanroepen van het script, roept de scriptprovider de ReportError-methode aan om de gebruikersinterface van de fout op de hoogte te stellen.
De hostcontext voor een script: IDataModelScriptHostContext
De host voor foutopsporing heeft enige invloed op hoe en waar het gegevensmodelscriptinhoud projecteert. Er wordt verwacht dat elk script de host vraagt om een context waarin bruggen naar het script moeten worden geplaatst (bijvoorbeeld functieobjecten die kunnen worden aangeroepen, enzovoort). Deze context wordt opgehaald via het aanroepen van de Methode CreateContext op IDebugHostScriptHost en het ophalen van een IDataModelScriptHostContext.
De interface IDataModelScriptHostContext wordt als volgt gedefinieerd.
DECLARE_INTERFACE_(IDataModelScriptHostContext, IUnknown)
{
STDMETHOD(NotifyScriptChange)(_In_ IDataModelScript* script, _In_ ScriptChangeKind changeKind) PURE;
STDMETHOD(GetNamespaceObject)(_COM_Outptr_ IModelObject** namespaceObject) PURE;
}
Het is vereist dat een scriptprovider de foutopsporingshost informeert bij bepaalde bewerkingen die plaatsvinden met een methodeaanroep naar de methode NotifyScriptChange in de bijbehorende context. Dergelijke bewerkingen worden gedefinieerd als leden van de opsomming ScriptChangeKind
De methode GetNamespaceObject retourneert een object waarin de scriptprovider bruggen tussen het gegevensmodel en het script kan plaatsen. Het is hier bijvoorbeeld dat de scriptprovider gegevensmodelmethodeobjecten (IModelMethod-interfaces in het vak IModelObject) kan plaatsen waarvan de implementatie wordt aangeroepen in overeenkomende benoemde functies in het script.
sjablonen voor nieuw gemaakte scripts: IDataModelScriptTemplate
Scriptproviders die vooraf ingevulde inhoud willen presenteren voor nieuwe scripts (bijvoorbeeld om gebruikers te helpen bij het schrijven van scripts in een gebruikersinterface voor foutopsporingsprogramma) kunnen dit doen door een of meer scriptsjablonen op te geven. Dergelijke sjablonen zijn onderdelen die de interface IDataModelScriptTemplate implementeren en worden geretourneerd via de Methode GetDefaultTemplate of DeumerateTemplates op de scriptprovider.
De interface IDataModelScriptTemplate wordt als volgt gedefinieerd.
DECLARE_INTERFACE_(IDataModelScriptTemplate, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *templateName) PURE;
STDMETHOD(GetDescription)(_Out_ BSTR *templateDescription) PURE;
STDMETHOD(GetContent)(_COM_Outptr_ IStream **contentStream) PURE;
}
De Methode GetName retourneert een naam van de sjabloon. Dit kan mislukken met E_NOTIMPL als de sjabloon geen naam heeft. De enkele standaardsjabloon (indien aanwezig) is niet vereist om een naam te hebben. Alle andere sjablonen zijn. Deze namen kunnen worden weergegeven in een gebruikersinterface als onderdeel van een menu om te selecteren welke sjabloon moet worden gemaakt.
De Methode GetDescription retourneert een beschrijving van de sjabloon. Een dergelijke beschrijving wordt aan de gebruiker gepresenteerd in meer beschrijvende interfaces om de gebruiker te helpen begrijpen wat de sjabloon moet doen. De sjabloon kan E_NOTIMPL van deze methode retourneren als deze geen beschrijving heeft.
De Methode GetContent retourneert de inhoud (of code) van de sjabloon. Dit is wat vooraf in het bewerkingsvenster wordt ingevuld als een gebruiker ervoor heeft gekozen om een nieuw script te maken op basis van deze sjabloon. De sjabloon is verantwoordelijk voor het maken (en retourneren) van een standaardstream via de inhoud die de client kan ophalen.
Opsomming van de sjablooninhoud van een provider: IDataModelScriptTemplateEnumerator
Een scriptprovider kan een of meer sjablonen bieden waarmee inhoud vooraf wordt ingevuld in nieuw gemaakte scripts in een gebruikersinterface. Als een van deze sjablonen wordt opgegeven, moet de scriptprovider een enumerator implementeren die wordt geretourneerd na een aanroep van de methode EnumerateTemplates.
Een dergelijke enumerator is een implementatie van de IDataModelScriptTemplateEnumerator-interface en wordt als volgt gedefinieerd.
DECLARE_INTERFACE_(IDataModelScriptTemplateEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptTemplate **templateContent) PURE;
}
Met de methode Reset wordt de enumerator opnieuw ingesteld op de positie waarop deze zich bevond toen deze voor het eerst werd gemaakt- voordat de eerste sjabloon werd geproduceerd.
De Methode GetNext verplaatst de enumerator naar de volgende sjabloon en retourneert deze. Aan het einde van de opsomming retourneert de opsomming E_BOUNDS. Zodra de E_BOUNDS markering is bereikt, blijft de opsommingsfunctie voor onbepaalde tijd E_BOUNDS fouten produceren totdat er een reset-aanroep wordt uitgevoerd.
De betekenis van namen omzetten: IDataModelNameBinder
Het gegevensmodel biedt een standaardmethode voor scriptproviders om de betekenis van een bepaalde naam in een bepaalde context te bepalen (bijvoorbeeld bepalen welke balk betekent voor foo.bar) die voor verschillende scriptproviders worden gebruikt. Dit mechanisme wordt een naambinding genoemd en wordt vertegenwoordigd door de interface IDataModelNameBinder. Zo'n binder bevat een set regels over hoe de naam wordt omgezet en hoe kan worden omgegaan met conflictoplossing waarbij een naam meerdere keren op een object wordt gedefinieerd. Een deel van deze regels omvat zaken zoals de manier waarop een projectnaam (één toegevoegd door een gegevensmodel) wordt omgezet op basis van een systeemeigen naam (een in het typesysteem van de taal waarop fouten worden opgespoord).
Om een zekere mate van consistentie te bieden tussen scriptproviders, biedt het scriptbeheer van het gegevensmodel een standaardnaambinding'. Deze standaardnaambinding kan worden verkregen via een aanroep naar de Methode GetDefaultNameBinder in de interface IDataModelScriptManager. De naambindingsinterface wordt als volgt gedefinieerd.
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;
}
De BindValue-methode voert het equivalent van contextObject.name uit op het opgegeven object volgens een set bindingsregels. Het resultaat van deze binding is een waarde. Als waarde kan de onderliggende scriptprovider de waarde niet gebruiken om de toewijzing terug naar naam uit te voeren.
De BindReference-methode is vergelijkbaar met BindValue omdat hiermee ook het equivalent van contextObject.name op het opgegeven object wordt uitgevoerd op basis van een set bindingsregels. Het resultaat van de binding uit deze methode is echter een verwijzing in plaats van een waarde. Als referentie kan de scriptprovider de verwijzing gebruiken om de toewijzing weer op naam uit te voeren.
De methode EnumerateValues bevat een opsomming van de set namen en waarden die worden gebonden aan het object volgens de regels van de methode BindValue. In tegenstelling tot de EnumerateKeys, EnumerateValues en vergelijkbare methoden op IModelObject, die meerdere namen met dezelfde waarde kunnen retourneren (voor basisklassen, bovenliggende modellen en dergelijke), retourneert deze enumerator alleen de specifieke set namen die binden met BindValue en BindReference. Namen worden nooit gedupliceerd. Houd er rekening mee dat er aanzienlijk hogere kosten zijn voor het inventariseren van een object via de naambinding dan het aanroepen van de IModelObject-methoden.
De methode EnumerateReferences inventariseert de set namen en verwijzingen die aan het object worden gekoppeld volgens de regels van de BindReference-methode. In tegenstelling tot de EnumerateKeys, EnumerateValues en vergelijkbare methoden op IModelObject, die meerdere namen met dezelfde waarde kunnen retourneren (voor basisklassen, bovenliggende modellen en dergelijke), retourneert deze enumerator alleen de specifieke set namen die binden met BindValue en BindReference. Namen worden nooit gedupliceerd. Houd er rekening mee dat er aanzienlijk hogere kosten zijn voor het inventariseren van een object via de naambinding dan het aanroepen van de IModelObject-methoden.
Foutopsporingsinterfaces voor gegevensmodel C++ voor foutopsporing
De infrastructuur voor scriptproviders in het gegevensmodel biedt ook een concept rond foutopsporingsscripts. Elk script dat foutopsporingsmogelijkheden beschikbaar wil maken voor de foutopsporingshost en de foutopsporingsprogrammatoepassing die als host fungeert voor het gegevensmodel, kan dit doen door foutopsporingsbare scripts te laten implementeren in aanvulling op de IDataModelScript-interface. De aanwezigheid van deze interface in het script geeft aan aan de infrastructuur dat deze foutopsporing kan worden uitgevoerd.
Hoewel de IDataModelScriptDebug-interface het startpunt is om toegang te krijgen tot de foutopsporingsmogelijkheden van een scriptprovider, wordt deze toegevoegd door een set andere interfaces om algemene foutopsporingsmogelijkheden te bieden.
De foutopsporingsinterfaces zijn:
| gebruikersinterface | Beschrijving |
|---|---|
| IDataModelScriptDebug | De kerninterface die een scriptprovider moet bieden om een script foutopsporing mogelijk te maken. De implementatieklasse van de IDataModelScript-interface moet QueryInterface voor IDataModelScriptDebug zijn als het script foutopsporingsbaar is. |
| IDataModelScriptDebugClient | De gebruikersinterface die de mogelijkheid van scriptopsporing wil bieden, implementeert de interface IDataModelScriptDebugClient. De scriptprovider maakt gebruik van deze interface om foutopsporingsinformatie heen en weer door te geven (bijvoorbeeld gebeurtenissen die optreden, onderbrekingspunten, enzovoort...) |
| IDataModelScriptDebugStack | De scriptprovider implementeert deze interface om het concept van een aanroepstack beschikbaar te maken voor het foutopsporingsprogramma voor scripts. |
| IDataModelScriptDebugStackFrame | De scriptprovider implementeert deze interface om het concept van een bepaald stackframe in de aanroepstack beschikbaar te maken. |
| IDataModelScriptDebugVariableSetEnumerator | De scriptprovider implementeert deze interface om een set variabelen beschikbaar te maken. Deze set kan de set parameters vertegenwoordigen voor een functie, de set lokale variabelen of de set variabelen binnen een bepaald bereik. De exacte betekenis is afhankelijk van hoe de interface is verkregen. |
| IDataModelScriptDebugBreakpoint | De scriptprovider implementeert deze interface om het concept van en het beheer van een bepaald onderbrekingspunt in het script beschikbaar te maken. |
| IDataModelScriptDebugBreakpointEnumerator | De scriptprovider implementeert dit om alle onderbrekingspunten op te sommen die momenteel aanwezig zijn in het script (al dan niet ingeschakeld). |
De algemene beheerinterfaces zijn:
| gebruikersinterface | Beschrijving |
|---|---|
| IDataModelScriptProvider | De kerninterface die een scriptprovider moet implementeren. Dit is de interface die is geregistreerd bij het scriptbeheergedeelte van de gegevensmodelbeheerder om de ondersteuning van de provider van een bepaald type script te adverteren en zich te registreren bij een bepaalde bestandsextensie |
| IDataModelScript | Een abstractie van een bepaald script dat wordt beheerd door de provider. Elk script dat wordt geladen of bewerkt, heeft een afzonderlijk IDataModelScript-exemplaar |
| IDataModelScriptClient | Een clientinterface die door de scriptprovider wordt gebruikt om informatie te communiceren met een gebruikersinterface. Scriptproviders implementeren deze interface niet. De toepassing die als host fungeert voor het gegevensmodel dat gebruik wil maken van scriptproviders. Een scriptprovider roept methoden van de scriptclient aan om de status, fouten, enzovoort te rapporteren... |
| IDataModelScriptHostContext | Een hostinterface die door de scriptprovider wordt gebruikt als een container voor de inhoud van het script. Hoe de inhoud van een scriptoppervlak anders is dan de manipulaties die het uitvoert voor het objectmodel van de foutopsporingsprogrammatoepassing, is aan de specifieke foutopsporingshost. Met deze interface kan de scriptprovider informatie ophalen over waar de inhoud ervan moet worden opgeslagen. |
| IDataModelScriptTemplate | Scriptproviders kunnen een of meer sjablonen bieden die fungeren als uitgangspunt voor gebruikers om scripts te schrijven. Een foutopsporingsprogrammatoepassing die een ingebouwde editor biedt, kan nieuwe scripts vooraf invullen met sjablooninhoud, zoals aangekondigd door de provider via deze interface. |
| IDataModelScriptTemplateEnumerator | Een enumerator-interface die door de scriptprovider wordt geïmplementeerd om alle verschillende sjablonen te adverteren die worden ondersteund. |
| IDataModelNameBinder | Een naambinding - een object dat een naam in een context kan koppelen aan een waarde. Voor een bepaalde expressie, zoals 'foo.bar', kan een naambinding de naambalk in de context van object 'foo' binden en een waarde of verwijzing naar het object produceren. Naambindingen worden doorgaans niet geïmplementeerd door een scriptprovider; in plaats daarvan kan de standaardbinding worden verkregen uit het gegevensmodel en worden gebruikt door de scriptprovider. |
Scripts debuggable maken: IDataModelScriptDebug
Elk script dat foutopsporingsbaar is, geeft deze mogelijkheid aan via de aanwezigheid van de IDataModelScriptDebug-interface op hetzelfde onderdeel dat IDataModelScript implementeert. De query voor deze interface door de foutopsporingshost of de foutopsporingsprogrammatoepassing die als host fungeert voor het gegevensmodel, geeft de aanwezigheid van de foutopsporingsmogelijkheid aan.
De interface IDataModelScriptDebug wordt als volgt gedefinieerd.
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;
}
De Methode GetDebugState retourneert de huidige status van het script (bijvoorbeeld of het nu wel of niet wordt uitgevoerd). De status wordt gedefinieerd door een waarde in de opsomming ScriptDebugState.
De methode GetCurrentPosition retourneert de huidige positie in het script. Dit kan alleen worden aangeroepen wanneer het script wordt opgesplitst in het foutopsporingsprogramma waarbij een aanroep naar GetScriptState ScriptDebugBreak retourneert. Een andere aanroep van deze methode is ongeldig en mislukt.
De GetStack-methode haalt de huidige aanroepstack op de onderbrekingspositie op. Deze methode kan alleen worden aangeroepen wanneer het script wordt opgesplitst in het foutopsporingsprogramma.
De methode SetBreakpoint stelt een onderbrekingspunt in het script in. Houd er rekening mee dat de implementatie gratis is om de inpassed lijn- en kolomposities aan te passen om verder te gaan naar een geschikte codepositie. De werkelijke regel- en kolomnummers waar het onderbrekingspunt is geplaatst, kunnen worden opgehaald door methodeaanroepen op de geretourneerde IDataModelScriptDebugBreakpoint-interface.
Aan elk onderbrekingspunt dat in het script wordt gemaakt via de Methode SetBreakpoint, wordt een unieke id (een 64-bits geheel getal zonder teken) toegewezen door de implementatie. De methode FindBreakpointById wordt gebruikt om een interface op te halen naar het onderbrekingspunt van een bepaalde id.
De methode EnumerateBreakpoints retourneert een enumerator die elk onderbrekingspunt kan inventariseren dat in een bepaald script is ingesteld.
De methode GetEventFilter retourneert of 'onderbreking bij gebeurtenis' is ingeschakeld voor een bepaalde gebeurtenis. Gebeurtenissen die 'onderbreking op gebeurtenis' kunnen veroorzaken, worden beschreven door een lid van de opsomming ScriptDebugEventFilter.
De methode SetEventFilter wijzigt het gedrag 'einde op gebeurtenis' voor een bepaalde gebeurtenis, zoals gedefinieerd door een lid van de opsomming ScriptDebugEventFilter. Een volledige lijst met beschikbare gebeurtenissen (en een beschrijving van deze opsomming) vindt u in de documentatie voor de Methode GetEventFilter.
Met de methode StartDebugging wordt het foutopsporingsprogramma voor een bepaald script ingeschakeld. De handeling van het starten van foutopsporing veroorzaakt geen uitvoeringsonderbreking of -stap. Het maakt het script alleen foutopsporing mogelijk en biedt een set interfaces voor de client om te communiceren met de foutopsporingsinterface.
De Methode StopDebugging wordt aangeroepen door een client die de foutopsporing wil stoppen. Deze methodeaanroep kan op elk moment worden uitgevoerd nadat StartDebugging is uitgevoerd (bijvoorbeeld tijdens een onderbreking, terwijl het script wordt uitgevoerd, enzovoort). De aanroep stopt onmiddellijk alle foutopsporingsactiviteit en stelt de status opnieuw in voordat StartDebugging werd aangeroepen.
de interface voor foutopsporing: IDataModelScriptDebugClient
De foutopsporingshost of foutopsporingsprogrammatoepassing die een interface wil bieden voor scriptopsporing, moet een implementatie van de IDataModelScriptDebugClient-interface bieden aan het scriptdebugger via de Methode StartDebugging op de foutopsporingsinterface voor het script.
De IDataModelScriptDebugClient is het communicatiekanaal waarmee foutopsporingsgebeurtenissen worden doorgegeven en het besturingselement van de scriptuitvoeringsengine naar een foutopsporingsprogramma-interface gaat. Deze wordt als volgt gedefinieerd.
DECLARE_INTERFACE_(IDataModelScriptDebugClient, IUnknown)
{
STDMETHOD(NotifyDebugEvent)(_In_ ScriptDebugEventInformation *pEventInfo, _In_ IDataModelScript *pScript, _In_opt_ IModelObject *pEventDataObject, _Inout_ ScriptExecutionKind *resumeEventKind) PURE;
}
Wanneer er een gebeurtenis optreedt die in het foutopsporingsprogramma voor scripts inbreekt, wordt de foutopsporingscode zelf aangeroepen naar de interface via de methode NotifyDebugEvent. Deze methode is synchroon. De uitvoering van het script wordt niet hervat totdat de interface van de gebeurtenis wordt geretourneerd. De definitie van het foutopsporingsprogramma voor scripts is bedoeld om eenvoudig te zijn: er zijn absoluut geen geneste gebeurtenissen die verwerking vereisen. Een foutopsporings gebeurtenis wordt gedefinieerd door een variantrecord, ook wel een ScriptDebugEventInformation genoemd. Welke velden in de gebeurtenisgegevens geldig zijn, wordt grotendeels gedefinieerd door het lid DebugEvent. Hiermee definieert u het soort gebeurtenis dat is opgetreden zoals beschreven door een lid van de opsomming ScriptDebugEvent.
De aanroepstack: IDataModelScriptDebugStack
Wanneer er een gebeurtenis optreedt die in het foutopsporingsprogramma voor scripts inbreekt, wil de foutopsporingsinterface de aanroepstack voor de onderbrekingslocatie ophalen. Dit wordt gedaan via de GetStack-methode. Een dergelijke stack wordt uitgedrukt via de IDataModelScriptDebugStack die is gedefinieerd zoals hieronder wordt aangegeven.
Houd er rekening mee dat de algehele stack meerdere scripts en/of meerdere scriptproviders kan omvatten. De aanroepstack die wordt geretourneerd van één aanroep naar de GetStack-methode op de foutopsporingsinterface van een bepaald script, mag alleen het segment van de aanroepstack binnen de grenzen van dat script retourneren. Het is volledig mogelijk dat een scriptfoutopsporingsengine de aanroepstack kan ophalen, omdat deze meerdere scriptcontexten omvat als twee scripts van dezelfde provider communiceren. De GetStack-methode mag het gedeelte van de stack dat zich in een ander script bevindt, niet retourneren. Als deze situatie kan worden gedetecteerd, moet het stackframe dat het grensframe in het script is, zichzelf markeren als een overgangsframe via een implementatie van de IsTransitionPoint- en GetTransition-methoden op dat stackframe. Er wordt verwacht dat de interface van het foutopsporingsprogramma de algehele stack van de meerdere stacksegmenten die bestaan, samenvoegen.
Het is noodzakelijk dat overgangen op deze manier worden geïmplementeerd of dat de foutopsporingsinterface vragen kan sturen over lokale variabelen, parameters, onderbrekingspunten en andere scriptspecifieke constructies naar de verkeerde scriptcontext. Dit leidt tot niet-gedefinieerd gedrag in de foutopsporingsprogramma-interface.
DECLARE_INTERFACE_(IDataModelScriptDebugStack, IUnknown)
{
STDMETHOD_(ULONG64, GetFrameCount)() PURE;
STDMETHOD(GetStackFrame)(_In_ ULONG64 frameNumber, _COM_Outptr_ IDataModelScriptDebugStackFrame **stackFrame) PURE;
}
De methode GetFrameCount retourneert het aantal stackframes in dit segment van de aanroepstack. Als de provider frames in verschillende scriptcontexten of van verschillende providers kan detecteren, moet dit aan de aanroeper worden aangegeven door de implementatie van de Methoden IsTransitionPoint en GetTransition in het invoerframe in dit stacksegment.
Het GetStackFrame haalt een bepaald stackframe op uit het stacksegment. De aanroepstack heeft een indexeringssysteem op basis van nul: het huidige stackframe waarin de onderbrekingsgebeurtenis heeft plaatsgevonden, is frame 0. De aanroeper van de huidige methode is frame 1 (enzovoort).
status onderzoeken wanneer deze is verbroken: IDataModelScriptDebugStackFrame
Een bepaald frame van de aanroepstack wanneer deze wordt opgesplitst in het foutopsporingsprogramma voor scripts, kan worden opgehaald via een aanroep naar de Methode GetStackFrame op de interface IDataModelScriptDebugStack die het stacksegment vertegenwoordigt waar de onderbreking is opgetreden. De IDataModelScriptDebugStackFrame-interface die wordt geretourneerd om dit frame aan te geven, wordt als volgt gedefinieerd.
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;
}
De methode GetName retourneert de weergavenaam (bijvoorbeeld functienaam) van dit frame. Deze naam wordt weergegeven in de stack-backtrace die wordt gepresenteerd aan de gebruiker in de interface voor foutopsporingsprogramma.
De GetPosition-methode retourneert de positie binnen het script dat wordt vertegenwoordigd door het stackframe. Deze methode kan alleen worden aangeroepen wanneer het script zich binnen een onderbreking bevindt die wordt vertegenwoordigd door de stack waarin dit frame zich bevindt. De lijn- en kolompositie binnen dit frame worden altijd geretourneerd. Als het foutopsporingsprogramma het bereik van de uitvoeringspositie binnen het script kan retourneren, kan een eindpositie worden geretourneerd in het argument positionSpanEnd. Als het foutopsporingsprogramma dit niet kan, moeten de lijn- en kolomwaarden in het bereikeind (indien aangevraagd) worden ingesteld op nul.
De interface IDataModelScriptDebugStack vertegenwoordigt een segment van een aanroepstack, dat deel van de aanroepstack die zich in de context van één script bevindt. Als het foutopsporingsprogramma de overgang van het ene script naar het andere kan detecteren (of de ene scriptprovider naar het andere), kan dit worden aangegeven door de Methode IsTransitionPoint te implementeren en waar of onwaar te retourneren, indien van toepassing. Het aanroepstackframe dat het script heeft ingevoerd waarop het segment van toepassing is, moet worden beschouwd als een overgangspunt. Alle andere frames zijn niet.
Als een bepaald stackframe een overgangspunt is zoals bepaald door de Methode IsTransition (zie de documentatie daar voor een definitie van overgangspunten), retourneert de Methode GetTransition informatie over de overgang. Deze methode retourneert met name het vorige script: het script dat een aanroep heeft gedaan in het script dat wordt vertegenwoordigd door het stacksegment dat dit IDataModelScriptDebugStackFrame bevat.
De methode Evaluate evalueert een expressie (van de taal van de scriptprovider) in de context van het stackframe dat wordt vertegenwoordigd door de interface IDataModelScriptDebugStackFrame waarop deze methode is aangeroepen. Het resultaat van de expressie-evaluatie moet worden marshaled uit de scriptprovider als een IModelObject. De eigenschappen en andere constructies op het resulterende IModelObject moeten allemaal kunnen worden verkregen terwijl het foutopsporingsprogramma een onderbrekingsstatus heeft.
De enumerateLocals-methode retourneert een variabelenset (vertegenwoordigd door een IDataModelScriptDebugVariableSetEnumerator-interface) voor alle lokale variabelen die binnen het bereik vallen in de context van het stackframe dat wordt vertegenwoordigd door de interface IDataModelScriptDebugStackFrame waarop deze methode werd aangeroepen.
De methode EnumerateArguments retourneert een variabelenset (vertegenwoordigd door een IDataModelScriptDebugVariableSetEnumerator-interface) voor alle functieargumenten van de functie die wordt aangeroepen in het stackframe dat wordt vertegenwoordigd door de interface IDataModelScriptDebugStackFrame waarop deze methode werd aangeroepen.
Variabelen bekijken: IDataModelScriptDebugVariableSetEnumerator
Een set variabelen in het script die wordt opgespoord (of deze zich in een bepaald bereik bevinden, de lokale bevolking van een functie, de argumenten van een functie, enzovoort...) wordt vertegenwoordigd door een variabelenset die is gedefinieerd via de 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;
}
Met de methode Reset wordt de positie van de enumerator opnieuw ingesteld op de plaats waar deze zich direct na het maken bevond, dat wil gezegd vóór het eerste element van de set.
De Methode GetNext verplaatst de enumerator naar de volgende variabele in de set en retourneert de naam, waarde en eventuele metagegevens die eraan zijn gekoppeld. Als de enumerator het einde van de set heeft bereikt, wordt de fout E_BOUNDS geretourneerd. Zodra de E_BOUNDS markering is geretourneerd uit de GetNext-methode, blijft deze E_BOUNDS produceren wanneer deze opnieuw wordt aangeroepen, tenzij er een tussenliggende aanroep Reset wordt gedaan.
onderbrekingspunten: IDataModelScriptDebugBreakpoint
Scriptonderbrekingspunten worden ingesteld via de Methode SetBreakpoint op de foutopsporingsinterface van een bepaald script. Dergelijke onderbrekingspunten worden vertegenwoordigd door zowel een unieke id als een implementatie van de IDataModelScriptDebugBreakpoint-interface die als volgt wordt gedefinieerd.
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;
}
De GetId-methode retourneert de unieke id die is toegewezen door de foutopsporingsengine van de scriptprovider aan het onderbrekingspunt. Deze id moet uniek zijn binnen de context van het bevatde script. De onderbrekingspunt-id kan uniek zijn voor de provider; dat is echter niet vereist.
De methode IsEnabled retourneert of het onderbrekingspunt al dan niet is ingeschakeld. Er bestaat nog steeds een uitgeschakeld onderbrekingspunt en bevindt zich nog steeds in de lijst met onderbrekingspunten voor het script. Het is slechts tijdelijk 'uitgeschakeld'. Alle onderbrekingspunten moeten worden gemaakt met de status Ingeschakeld.
Met de methode Inschakelen wordt het onderbrekingspunt ingeschakeld. Als het onderbrekingspunt is uitgeschakeld, zorgt 'het bereiken van het onderbrekingspunt' na het aanroepen van deze methode voor een onderbreking in het foutopsporingsprogramma.
Met de methode Uitschakelen wordt het onderbrekingspunt uitgeschakeld. Na deze aanroep wordt 'het onderbrekingspunt bereikt' nadat deze methode is aangeroepen, niet ingebroken in het foutopsporingsprogramma. Het onderbrekingspunt, terwijl het nog aanwezig is, wordt beschouwd als 'uitgeschakeld'.
Met de methode Remove wordt het onderbrekingspunt verwijderd uit de bijbehorende lijst. Het onderbrekingspunt bestaat niet langer semantisch nadat deze methode is geretourneerd. De IDataModelScriptDebugBreakpoint-interface die het onderbrekingspunt vertegenwoordigde, wordt beschouwd als zwevend na de aanroep. Niets anders kan er (wettelijk) mee worden gedaan na deze aanroep anders dan het vrijgeven ervan.
De GetPosition-methode retourneert de positie van het onderbrekingspunt in het script. Het foutopsporingsprogramma voor scripts moet de regel en kolom in de broncode retourneren waar het onderbrekingspunt zich bevindt. Als dit mogelijk is, kan het ook een bereik van de bron retourneren dat wordt vertegenwoordigd door het onderbrekingspunt door een eindpositie in te vullen zoals gedefinieerd door het argument positionSpanEnd. Als het foutopsporingsprogramma dit bereik niet kan produceren en de aanroeper dit aanvraagt, moeten de velden Lijn en Kolom van de eindpositie van de spanwijdte worden ingevuld als nul die aangeeft dat de waarden niet kunnen worden opgegeven.
Opsomming onderbrekingspunt: IDataModelScriptDebugBreakpointEnumerator
Als een scriptprovider foutopsporing ondersteunt, moet deze ook alle onderbrekingspunten bijhouden die zijn gekoppeld aan elk en elk script en deze onderbrekingspunten kunnen inventariseren in de foutopsporingsinterface. De enumerator voor onderbrekingspunten wordt verkregen via de EnumerateBreakpoints-methode op de foutopsporingsinterface voor een bepaald script en wordt als volgt gedefinieerd.
DECLARE_INTERFACE_(IDataModelScriptDebugBreakpointEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptDebugBreakpoint **breakpoint) PURE;
}
Met de methode Reset wordt de positie van de enumerator opnieuw ingesteld op de plaats waar deze zich net nadat de enumerator is gemaakt - dat wil gezegd vóór het eerste opsommingspunt.
De GetNext-methode verplaatst de enumerator naar het volgende onderbrekingspunt dat moet worden geïnventariseerd en retourneert de IDataModelScriptDebugBreakpoint-interface voor dat onderbrekingspunt. Als de opsomming het einde van de opsomming heeft bereikt, wordt E_BOUNDS geretourneerd. Zodra de E_BOUNDS fout is gegenereerd, blijven volgende aanroepen naar de Methode GetNext E_BOUNDS produceren, tenzij er een tussenliggende aanroep naar de methode Reset is gedaan.
Zie ook
Dit onderwerp maakt deel uit van een reeks waarin de interfaces worden beschreven die toegankelijk zijn vanuit C++, hoe u deze kunt gebruiken om een C++-extensie voor foutopsporingsprogramma's te bouwen en hoe u andere gegevensmodelconstructies (bijvoorbeeld JavaScript of NatVis) gebruikt vanuit een C++-gegevensmodelextensie.
Overzicht Foutopsporingsprogramma voor gegevensmodel C++
Foutopsporingsprogramma-gegevensmodel C++ interfaces
Gegevensmodel C++-objecten voor foutopsporingsprogramma's
Foutopsporingsprogramma voor gegevensmodel C++ aanvullende interfaces