Scripting C++ del modello di dati del debugger
Questo argomento descrive come usare script C++ Debugger Data Model C++ debugger per supportare l'automazione con il motore di debugger tramite scripting.
Gestione script nel modello di dati del debugger
Oltre al ruolo di Data Model Manager come autorità centrale per la creazione e l'estendibilità degli oggetti, è anche responsabile della gestione di un concetto astratto di script. Dal punto di vista della parte di Gestione script di Gestione modelli di dati, uno script è un elemento che può essere caricato, scaricato e potenzialmente sottoposto a debug da un provider per estendere o fornire nuove funzionalità al modello di dati.
Un provider di script è un componente che collega un linguaggio ,ad esempio NatVis, JavaScript e così via, al modello di dati. Registra una o più estensioni di file , ad esempio ". NatVis", ".js") gestiti dal provider che consentono a un client del debugger o a un'interfaccia utente di consentire il caricamento di file di script con tale estensione specifica tramite delega al provider.
The Core Script Manager: IDataModelScriptManager
L'interfaccia principale di Gestione script viene definita come segue.
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;
}
Il metodo GetDefaultNameBinder restituisce lo strumento di associazione dei nomi di script predefinito del modello di dati. Un gestore di associazione di nomi è un componente che risolve un nome all'interno del contesto di un oggetto. Ad esempio, data l'espressione "foo.bar", viene chiamato un gestore di associazione dei nomi per risolvere la barra dei nomi nel contesto del foo dell'oggetto. Il binder restituito di seguito segue un set di regole predefinite per il modello di dati. I provider di script possono usare questo binder per garantire coerenza nella risoluzione dei nomi tra provider.
Il metodo RegisterScriptProvider informa il modello di dati che esiste un nuovo provider di script in grado di colmare un nuovo linguaggio al modello di dati. Quando questo metodo viene chiamato, lo script manager richiamerà immediatamente il provider di script specificato e chiederà le proprietà degli script gestiti. Se esiste già un provider registrato con il nome o l'estensione di file che indica il provider di script specificato, questo metodo avrà esito negativo. Solo un singolo provider di script può essere registrato come gestore per un nome o un'estensione di file specifica.
Il metodo UnregisterScriptProvider annulla una chiamata al metodo RegisterScriptProvider. Il nome e l'estensione di file specificati dal provider di script inpassato non saranno più associati. È importante notare che potrebbe esserci un numero significativo di riferimenti COM in sospeso al provider di script anche dopo l'annullamento della registrazione. Questo metodo impedisce solo il caricamento o la creazione di script del tipo gestito dal provider di script specificato. Se uno script caricato da tale provider è ancora caricato o ha modificato il modello a oggetti del debugger (o del modello di dati), tali modifiche potrebbero comunque avere riferimenti allo script. Possono essere presenti modelli di dati, metodi o oggetti che fanno riferimento direttamente ai costrutti nello script. È necessario che un provider di script sia pronto a gestirlo.
Il metodo FindProviderForScriptType cerca nel gestore di script un provider con una stringa di tipo script, come indicato in questo metodo. Se non ne è possibile trovare uno, questo metodo avrà esito negativo; in caso contrario, tale provider di script verrà restituito al chiamante.
Il metodo EnumerateScriptProviders restituirà un enumeratore che enumererà ogni provider di script registrato con lo script manager tramite una chiamata precedente al metodo RegisterScriptProvider.
Enumerazione provider script: IDataModelScriptProviderEnumerator
Il metodo EnumerateScriptProviders restituirà un enumeratore del formato seguente:
DECLARE_INTERFACE_(IDataModelScriptProviderEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptProvider **provider) PURE;
}
Il metodo Reset sposta l'enumeratore nella posizione in cui si trovava prima di restituire il primo elemento.
Il metodo GetNext sposta l'enumeratore avanti un elemento e restituisce il provider di script che si trova in tale elemento. Quando l'enumeratore raggiunge la fine dell'enumerazione, E_BOUNDS verrà restituito. La chiamata al metodo GetNext dopo la ricezione di questo errore continuerà a restituire E_BOUNDS all'infinito.
Interfacce host C++ del modello di dati del debugger per lo scripting
Ruolo dell'host nello scripting
L'host di debug espone una serie di interfacce di livello molto basso per comprendere la natura del sistema di tipi delle destinazioni di debug, la valutazione delle espressioni nel linguaggio delle destinazioni di debug e così via... In genere, non è associato a costrutti di livello superiore, ad esempio scripting. Tali elementi vengono lasciati all'applicazione debugger complessiva o alle estensioni che forniscono queste funzionalità. Esiste tuttavia un'eccezione a questo. Qualsiasi host di debug che vuole partecipare all'esperienza di scripting complessiva offerta dal modello di dati deve implementare alcune semplici interfacce per fornire contesti agli script. In effetti, l'host di debug è in controllo della posizione in cui vuole che l'ambiente di scripting inserisca funzioni e altre funzionalità fornite dallo script all'interno dello spazio dei nomi del modello di dati. Essere coinvolti in questo processo consente all'host di consentire (o meno) l'uso di tali funzioni in, ad esempio, il relativo analizzatore di espressioni. Di seguito sono riportate le interfacce coinvolte dal punto di vista dell'host:
| Interfaccia | Descrizione |
|---|---|
| IDebugHostScriptHost | Interfaccia che indica la capacità dell'host di debug di partecipare all'ambiente di scripting. Questa interfaccia consente la creazione di contesti che informano i motori di scripting della posizione degli oggetti. |
| IDataModelScriptHostContext | Interfaccia host usata dal provider di script come contenitore per il contenuto dello script. La modalità di esecuzione del contenuto di una superficie di script diversa dalle manipolazioni eseguite nel modello a oggetti dell'applicazione debugger dipende dall'host di debug specifico. Questa interfaccia consente al provider di script di ottenere informazioni su dove posizionarne il contenuto. Per altre informazioni, vedere Interfacce di scripting C++ del modello di dati più avanti in questo argomento. |
Host script dell'host di debug: IDebugHostScriptHost
L'interfaccia IDebugHostScriptHost è l'interfaccia usata da un provider di script per ottenere un contesto dall'host di debug per uno script appena creato. Questo contesto include un oggetto (fornito dall'host di debug) in cui il provider di script può posizionare qualsiasi bridge tra il modello di dati e l'ambiente di scripting. Tali bridge potrebbero, ad esempio, essere metodi del modello di dati che richiamano funzioni script. In questo modo, un chiamante sul lato modello di dati può richiamare i metodi di script usando il metodo Call nell'interfaccia IModelMethod.
L'interfaccia IDebugHostScriptHost è definita come segue.
DECLARE_INTERFACE_(IDebugHostScriptHost, IUnknown)
{
STDMETHOD(CreateContext)(_In_ IDataModelScript* script, _COM_Outptr_ IDataModelScriptHostContext** scriptContext) PURE;
}
Il metodo CreateContext viene chiamato da un provider di script per creare un nuovo contesto in cui inserire il contenuto dello script. Tale contesto è rappresentato dall'interfaccia IDataModelScriptHostContext descritta in dettaglio nella pagina Interfacce di scripting C++ del modello di dati.
Interfacce di scripting C++ del modello di dati del debugger
Scripting e interfacce script
L'architettura complessiva del modello di dati consente a terze parti di definire un bridge tra un linguaggio e il modello a oggetti del modello di dati. In genere, il linguaggio sottoposto a bridge è un linguaggio di scripting perché l'ambiente del modello di dati è molto dinamico. Un componente che definisce e implementa questo bridge tra un linguaggio e il modello a oggetti del modello di dati è denominato provider di script. Quando inizializzato, un provider di script si registra con la parte di gestione script del gestore modelli di dati e qualsiasi interfaccia che gestisce l'estendibilità consentirà successivamente la modifica, il caricamento, lo scaricamento e il debug di script scritti nel linguaggio gestito dal provider di script.
Si noti che gli strumenti di debug per Windows definiscono attualmente due provider di script.
- Provider NatVis. Questo provider è incorporato all'interno di DbgEng.dll e bridge tra natVis XML e modelli di dati, consentendo la visualizzazione dei tipi di dati nativi/linguistici.
- Provider JavaScript. Questo provider è contenuto in un'estensione del debugger legacy: JsProvider.dll. Esegue il bridge tra gli script scritti nel linguaggio JavaScript e il modello di dati, consentendo forme arbitrarie di controllo ed estendibilità del debugger.
I nuovi provider possono essere scritti per collegare altri linguaggi (ad esempio, Python e così via) al modello di dati. Tali elementi verranno attualmente incapsulati nelle estensioni del debugger legacy a scopo di caricamento. Il provider di script stesso deve ridurre al minimo la dipendenza con le interfacce del motore legacy e deve usare solo le API del modello di dati laddove possibile. Ciò consentirà al provider di essere reso portabile in altri ambienti con una maggiore facilità.
Esistono due classi di interfacce correlate ai provider di script. La prima classe di interfacce è per la gestione generale dei provider di script e degli script gestiti. La seconda classe di interfacce è per il supporto del debug di script. Anche se il supporto per il primo set è obbligatorio, il supporto per il secondo è facoltativo e potrebbe non avere senso per ogni provider.
Le interfacce di gestione generali sono:
| Interfaccia | Descrizione |
|---|---|
| IDataModelScriptProvider | Interfaccia principale che un provider di script deve implementare. Si tratta dell'interfaccia registrata con la parte di gestione script di Gestione modelli di dati per annunciare il supporto del provider di un particolare tipo di script e registrarsi su una determinata estensione di file |
| IDataModelScript | Astrazione di uno script specifico gestito dal provider. Ogni script caricato o modificato ha un'istanza IDataModelScript separata |
| IDataModelScriptClient | Interfaccia client usata dal provider di script per comunicare informazioni a un'interfaccia utente. I provider di script non implementano questa interfaccia. L'applicazione che ospita il modello di dati che desidera usare i provider di script. Un provider di script chiamerà i metodi del client di script per segnalare lo stato, gli errori e così via... |
| IDataModelScriptHostContext | Interfaccia host usata dal provider di script come contenitore per il contenuto dello script. Come il contenuto di una superficie di script diverso dalle manipolazioni eseguite per il modello a oggetti dell'applicazione debugger è fino all'host di debug specifico. Questa interfaccia consente al provider di script di ottenere informazioni su dove posizionarne il contenuto. |
| IDataModelScriptTemplate | I provider di script possono fornire uno o più modelli che fungono da punti di partenza per gli utenti per creare script. Un'applicazione debugger che fornisce un editor predefinito può precompilare nuovi script con contenuto modello come annunciato dal provider tramite questa interfaccia. |
| IDataModelScriptTemplateEnumerator | Interfaccia enumeratore che il provider di script implementa per annunciare tutti i vari modelli supportati. |
| IDataModelNameBinder | Un bindinger dei nomi: un oggetto che può associare un nome in un contesto a un valore. Per un'espressione specificata, ad esempio "foo.bar", un bindinger nome è in grado di associare il nome "bar" nel contesto dell'oggetto "foo" e produrre un valore o un riferimento a esso. I bindinger dei nomi non vengono in genere implementati da un provider di script; invece, il binder predefinito può essere acquisito dal modello di dati e usato dal provider di script |
Le interfacce di debug sono:
| Interfaccia | Descrizione |
|---|---|
| IDataModelScriptDebug | L'interfaccia di base che un provider di script deve fornire per rendere possibile il debug di uno script. La classe di implementazione dell'interfaccia IDataModelScript deve Eseguire QueryInterface per IDataModelScriptDebug se lo script è debugabile. |
| IDataModelScriptDebugClient | L'interfaccia utente che desidera fornire la funzionalità di debug dello script implementa l'interfaccia IDataModelScriptDebugClient. Il provider di script usa questa interfaccia per passare le informazioni di debug indietro e indietro (ad esempio, eventi che si verificano, punti di interruzione e così via...) |
| IDataModelScriptDebugStack | Il provider di script implementa questa interfaccia per esporre la nozione di stack di chiamate al debugger di script. |
| IDataModelScriptDebugStackFrame | Il provider di script implementa questa interfaccia per esporre la nozione di un particolare frame dello stack all'interno dello stack di chiamate. |
| IDataModelScriptDebugVariableSetEnumerator | Il provider di script implementa questa interfaccia per esporre un set di variabili. Questo set può rappresentare il set di parametri su una funzione, il set di variabili locali o il set di variabili all'interno di un determinato ambito. Il significato esatto dipende dalla modalità di acquisizione dell'interfaccia. |
| IDataModelScriptDebugBreakpoint | Il provider di script implementa questa interfaccia per esporre la nozione di e il controllo di un punto di interruzione specifico all'interno dello script. |
| IDataModelScriptDebugBreakpointEnumerator | Il provider di script implementa questa operazione per enumerare tutti i punti di interruzione che attualmente esistono all'interno dello script (sia abilitati che non). |
Provider di script di base: IDataModelScriptProvider
Qualsiasi estensione che vuole essere un provider di script deve fornire un'implementazione dell'interfaccia IDataModelScriptProvider e registrare tale estensione con la parte gestione script della gestione modelli di dati tramite il metodo RegisterScriptProvider. Questa interfaccia di base che deve essere implementata è definita come segue.
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;
}
Il metodo GetName restituisce il nome del tipo di script (o lingua di) gestiti dal provider come stringa allocata tramite il metodo SysAllocString. Il chiamante è responsabile della liberazione della stringa restituita tramite SysFreeString. Esempi di stringhe che potrebbero essere restituite da questo metodo sono "JavaScript" o "NatVis". La stringa restituita è probabilmente visualizzata nell'interfaccia utente dell'applicazione debugger che ospita il modello di dati. Nessun provider di script può restituire lo stesso nome (senza distinzione tra maiuscole e minuscole).
Il metodo GetExtension restituisce l'estensione del file per gli script gestiti da questo provider (senza punto) come stringa allocata tramite il metodo SysAllocString. L'applicazione debugger che ospita il modello di dati (con supporto per script) delega l'apertura dei file di script con questa estensione al provider di script. Il chiamante è responsabile della liberazione della stringa restituita tramite SysFreeString. Esempi di stringhe che potrebbero essere restituite da questo metodo sono "js" o "NatVis".
Il metodo CreateScript viene chiamato per creare un nuovo script. Il provider di script deve restituire uno script nuovo e vuoto rappresentato dall'interfaccia IDataModelScript restituita ogni volta che viene chiamato questo metodo. Si noti che questo metodo viene chiamato indipendentemente dal fatto che un'interfaccia utente stia creando un nuovo script vuoto per la modifica da parte dell'utente o se l'applicazione debugger sta caricando uno script da disco. Il provider non viene coinvolto nell'I/O del file. Gestisce semplicemente le richieste dall'applicazione di hosting tramite flussi passati ai metodi in IDataModelScript.
Il metodo GetDefaultTemplateContent restituisce un'interfaccia per il contenuto del modello predefinito del provider. Questo è il contenuto che il provider di script vuole precompilato in una finestra di modifica per uno script appena creato. Se il provider di script non dispone di modelli (o non dispone di contenuto modello designato come contenuto predefinito), il provider di script può restituire E_NOTIMPL da questo metodo.
Il metodo EnumerateTemplates restituisce un enumeratore in grado di enumerare l'ampia gamma di modelli forniti dal provider di script. Il contenuto del modello è quello che il provider di script vuole essere "precompilato" in una finestra di modifica durante la creazione di un nuovo script. Se sono supportati più modelli diversi, questi modelli possono essere denominati (ad esempio: "Script imperativo", "Script di estensione") e l'applicazione debugger che ospita il modello di dati può scegliere come presentare i "modelli" all'utente.
Interfaccia script di base: IDataModelScript
L'interfaccia principale che gestisce un singolo script implementato dal provider è l'interfaccia IDataModelScript. Un componente che implementa questa interfaccia viene restituito quando il client vuole creare un nuovo script vuoto e chiama il metodo CreateScript in IDataModelScriptProvider.
Ogni script creato dal provider deve trovarsi in un silo indipendente. Uno script non deve essere in grado di influire su un altro script, ad eccezione dell'interazione esplicita con oggetti esterni tramite il modello di dati. Due script, ad esempio, possono estendere un tipo o un concetto (ad esempio, la nozione del debugger di ciò che è un processo). Uno script può quindi accedere ai campi dell'altro tramite l'oggetto processo esterno.
L'interfaccia è definita come segue.
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;
}
Il metodo GetName restituisce il nome dello script come stringa allocata tramite la funzione SysAllocString. Se lo script non ha ancora un nome, il metodo deve restituire un BSTR null. Non dovrebbe riuscire in questa circostanza. Se lo script viene rinominato in modo esplicito tramite una chiamata al metodo Rinomina, il metodo GetName deve restituire il nome appena assegnato.
Il metodo Rinomina assegna un nuovo nome allo script. È responsabilità dell'implementazione dello script salvare questo nome e restituirlo a qualsiasi chiamata al metodo GetName. Questo viene spesso chiamato quando un'interfaccia utente sceglie di salvare come script in un nuovo nome. Si noti che la ridenominazione dello script può influire sulla posizione in cui l'applicazione di hosting sceglie di proiettare il contenuto dello script.
Il metodo Popolamento viene chiamato dal client per modificare o sincronizzare il "contenuto" dello script. Si tratta della notifica effettuata al provider di script che il codice dello script è stato modificato. È importante notare che questo metodo non causa l'esecuzione dello script o le modifiche a uno degli oggetti che lo script modifica. Si tratta semplicemente di una notifica al provider di script che il contenuto dello script è cambiato in modo che possa sincronizzare il proprio stato interno.
Il metodo Execute esegue il contenuto dello script come determinato dall'ultima chiamata Popolamento riuscita e modifica il modello a oggetti del debugger in base a tale contenuto. Se il linguaggio (o il provider di script) definisce una "funzione principale", una che l'autore vuole chiamare facendo clic su un pulsante "Esegui script" immaginari in un'interfaccia utente, tale "funzione principale" non viene chiamata durante un'operazione Di esecuzione. L'operazione Execute può essere considerata come eseguire l'inizializzazione e le manipolazioni dei modelli a oggetti (ad esempio l'esecuzione del codice radice e la configurazione di punti di estendibilità).
Il metodo Unlink annulla l'operazione Execute. Le manipolazioni o i punti di estendibilità dei modelli a oggetti stabiliti durante l'esecuzione dello script vengono annullati. Dopo un'operazione di scollegamento, lo script può essere eseguito nuovamente tramite una chiamata a Esegui o può essere rilasciato.
Il metodo IsInvocable restituisce se lo script è chiamabile, ovvero se ha una "funzione principale" come definito dal linguaggio o dal provider. Tale "funzione principale" è concettualmente qualcosa che l'autore dello script vuole chiamare se un pulsante "Esegui script" immaginario è stato premuto in un'interfaccia utente.
Se lo script ha una "funzione main" che deve essere eseguita da una chiamata dell'interfaccia utente, indica tale operazione tramite un vero ritorno dal metodo IsInvocable. L'interfaccia utente può quindi chiamare il metodo InvokeMain per "richiamare" effettivamente lo script. Si noti che questo comportamento è diverso da Execute che esegue tutto il codice radice e collega lo script allo spazio dei nomi dell'host sottostante.
**Client script: IDataModelScriptClient **
Un'applicazione che ospita il modello di dati che vuole gestire gli script e avere un'interfaccia utente (grafica o console) intorno a questo concetto implementa l'interfaccia IDataModelScriptClient. Questa interfaccia viene passata a qualsiasi provider di script durante l'esecuzione o la chiamata o uno script per passare le informazioni sugli errori e sugli eventi all'interfaccia utente.
L'interfaccia IDataModelScriptClient è definita come segue.
DECLARE_INTERFACE_(IDataModelScriptClient, IUnknown)
{
STDMETHOD(ReportError)(_In_ ErrorClass errClass, _In_ HRESULT hrFail, _In_opt_ PCWSTR message, _In_ ULONG line, _In_ ULONG position) PURE;
}
Se si verifica un errore durante l'esecuzione o la chiamata dello script, il provider di script chiama il metodo ReportError per notificare all'interfaccia utente l'errore.
Contesto host per uno script: IDataModelScriptHostContext
L'host di debug ha un'influenza su come e dove proietta il contenuto dello script del modello di dati. È previsto che ogni script chieda all'host un contesto in cui inserire bridge allo script (ad esempio, oggetti funzione che possono essere chiamati e così via). Questo contesto viene recuperato chiamando il metodo CreateContext in IDebugHostScriptHost e ottenendo un IDataModelScriptHostContext.
L'interfaccia IDataModelScriptHostContext è definita come segue.
DECLARE_INTERFACE_(IDataModelScriptHostContext, IUnknown)
{
STDMETHOD(NotifyScriptChange)(_In_ IDataModelScript* script, _In_ ScriptChangeKind changeKind) PURE;
STDMETHOD(GetNamespaceObject)(_COM_Outptr_ IModelObject** namespaceObject) PURE;
}
È necessario che un provider di script comunica all'host di debug in caso di determinate operazioni che si verificano con una chiamata al metodo NotifyScriptChange nel contesto associato. Tali operazioni vengono definite come membri dell'enumerazione ScriptChangeKind
Il metodo GetNamespaceObject restituisce un oggetto in cui il provider di script può inserire qualsiasi bridge tra il modello di dati e lo script. È qui, ad esempio, che il provider di script potrebbe inserire oggetti metodo del modello di dati (interfacce IModelMethod boxed in IModelObject) le cui implementazioni chiamano in funzioni denominate corrispondenti nello script.
Modelli per gli script appena creati: IDataModelScriptTemplate
I provider di script che vogliono presentare contenuto precompilato per i nuovi script (ad esempio, per aiutare gli utenti a scrivere script in un'interfaccia utente del debugger) possono farlo fornendo uno o più modelli di script. Tali modelli sono componenti che implementano l'interfaccia IDataModelScriptTemplate e vengono restituiti tramite il metodo GetDefaultTemplate o EnumerateTemplates nel provider di script.
L'interfaccia IDataModelScriptTemplate è definita come segue.
DECLARE_INTERFACE_(IDataModelScriptTemplate, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *templateName) PURE;
STDMETHOD(GetDescription)(_Out_ BSTR *templateDescription) PURE;
STDMETHOD(GetContent)(_COM_Outptr_ IStream **contentStream) PURE;
}
Il metodo GetName restituisce un nome del modello. Questo errore potrebbe non riuscire con E_NOTIMPL se il modello non ha un nome. Il singolo modello predefinito (se presente) non deve avere un nome. Tutti gli altri modelli sono. Questi nomi possono essere presentati in un'interfaccia utente come parte di un menu per selezionare il modello da creare.
Il metodo GetDescription restituisce una descrizione del modello. Tale descrizione verrà presentata all'utente in interfacce più descrittive per aiutare l'utente a comprendere cosa è progettato per eseguire il modello. Il modello può restituire E_NOTIMPL da questo metodo se non ha una descrizione.
Il metodo GetContent restituisce il contenuto (o il codice) del modello. Questo è ciò che verrebbe precompilato nella finestra di modifica se un utente ha scelto di creare un nuovo script da questo modello. Il modello è responsabile della creazione (e della restituzione) di un flusso standard sul contenuto che il client può eseguire il pull.
Enumerazione del contenuto del modello di un provider: IDataModelScriptTemplateEnumerator
Un provider di script può fornire uno o più modelli che precompilano il contenuto negli script appena creati in un'interfaccia utente. Se vengono forniti uno di questi modelli, il provider di script deve implementare un enumeratore su di essi che viene restituito dopo una chiamata al metodo EnumerateTemplates.
Tale enumeratore è un'implementazione dell'interfaccia IDataModelScriptTemplateEnumerator e viene definita come segue.
DECLARE_INTERFACE_(IDataModelScriptTemplateEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptTemplate **templateContent) PURE;
}
Il metodo Reset reimposta l'enumeratore sulla posizione in cui è stato creato per la prima volta, prima della creazione del primo modello.
Il metodo GetNext sposta l'enumeratore nel modello successivo e lo restituisce. Alla fine dell'enumerazione, l'enumeratore restituisce E_BOUNDS. Una volta raggiunto il E_BOUNDS marcatore, l'enumeratore continuerà a produrre errori E_BOUNDS all'infinito fino a quando non viene effettuata una chiamata di reimpostazione.
Risoluzione del significato dei nomi: IDataModelNameBinder
Il modello di dati fornisce un modo standard per i provider di script per determinare il significato di un determinato nome in un determinato contesto (ad esempio, determinare il significato della barra per foo.bar) che funzionerà in un'ampia gamma di provider di script. Questo meccanismo è noto come gestore di associazione dei nomi ed è rappresentato dall'interfaccia IDataModelNameBinder. Un gestore di associazione di questo tipo incapsula un set di regole sul modo in cui il nome viene risolto e come gestire la risoluzione dei conflitti in cui un nome viene definito più volte in un oggetto. Parte di queste regole includono elementi come il modo in cui un nome proiettato (uno aggiunto da un modello di dati) viene risolto in base a un nome nativo (uno nel sistema di tipi del linguaggio sottoposto a debug).
Per garantire un grado di coerenza tra provider di script, lo script manager del modello di dati fornisce un gestore di associazione dei nomi predefinito'. Questo gestore di associazione di nomi predefinito può essere acquisito tramite una chiamata al metodo GetDefaultNameBinder nell'interfaccia IDataModelScriptManager. L'interfaccia del gestore di associazione dei nomi è definita come segue.
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;
}
Il metodo BindValue esegue l'equivalente di contextObject.name sull'oggetto specificato in base a un set di regole di associazione. Il risultato di questa associazione è un valore. Come valore, il provider di script sottostanti non può usare il valore per eseguire nuovamente l'assegnazione al nome.
Il metodo BindReference è simile a BindValue in quanto esegue anche l'equivalente di contextObject.name sull'oggetto specificato in base a un set di regole di associazione. Il risultato dell'associazione da questo metodo è, tuttavia, un riferimento anziché un valore. Come riferimento, il provider di script può usare il riferimento per eseguire nuovamente l'assegnazione al nome.
Il metodo EnumerateValues enumera il set di nomi e valori che verranno associati all'oggetto in base alle regole del metodo BindValue. A differenza di EnumerateKeys, EnumerateValues e metodi simili in IModelObject che possono restituire più nomi con lo stesso valore (per classi di base, modelli padre e simili), questo enumeratore restituirà solo il set specifico di nomi che verranno associati a BindValue e BindReference. I nomi non verranno mai duplicati. Si noti che l'enumerazione di un oggetto tramite lo strumento di associazione dei nomi prevede un costo notevolmente superiore rispetto alla chiamata dei metodi IModelObject.
Il metodo EnumerateReferences enumera il set di nomi e riferimenti a essi che verrà associato all'oggetto in base alle regole del metodo BindReference. A differenza di EnumerateKeys, EnumerateValues e metodi simili in IModelObject che possono restituire più nomi con lo stesso valore (per classi di base, modelli padre e simili), questo enumeratore restituirà solo il set specifico di nomi che verranno associati a BindValue e BindReference. I nomi non verranno mai duplicati. Si noti che l'enumerazione di un oggetto tramite lo strumento di associazione dei nomi prevede un costo notevolmente superiore rispetto alla chiamata dei metodi IModelObject.
Interfacce di debug di script C++ del modello di dati del debugger
L'infrastruttura per i provider di script nel modello di dati fornisce anche un concetto di debug degli script. Qualsiasi script che desidera esporre le funzionalità di debug all'host di debug e all'applicazione debugger che ospita il modello di dati può eseguire questa operazione tramite script di debug che implementano l'interfaccia IDataModelScriptDebug oltre all'interfaccia IDataModelScript. La presenza di questa interfaccia nello script indica all'infrastruttura di cui è possibile eseguire il debug.
Anche se l'interfaccia IDataModelScriptDebug è il punto di partenza per ottenere l'accesso alle funzionalità di debug di un provider di script, viene unita da un set di altre interfacce per offrire funzionalità di debug complessive.
Le interfacce di debug sono:
| Interfaccia | Descrizione |
|---|---|
| IDataModelScriptDebug | Interfaccia di base che un provider di script deve fornire per rendere possibile il debug di uno script. La classe di implementazione dell'interfaccia IDataModelScript deve essere QueryInterface per IDataModelScriptDebug se lo script è debug. |
| IDataModelScriptDebugClient | L'interfaccia utente che vuole fornire la funzionalità di debug degli script implementa l'interfaccia IDataModelScriptDebugClient. Il provider di script usa questa interfaccia per passare le informazioni di debug avanti e indietro (ad esempio, eventi che si verificano, punti di interruzione e così via...) |
| IDataModelScriptDebugStack | Il provider di script implementa questa interfaccia per esporre la nozione di stack di chiamate al debugger di script. |
| IDataModelScriptDebugStackFrame | Il provider di script implementa questa interfaccia per esporre la nozione di un particolare stack frame all'interno dello stack di chiamate. |
| IDataModelScriptDebugVariableSetEnumerator | Il provider di script implementa questa interfaccia per esporre un set di variabili. Questo set può rappresentare il set di parametri di una funzione, il set di variabili locali o il set di variabili all'interno di un determinato ambito. Il significato esatto dipende dalla modalità di acquisizione dell'interfaccia. |
| IDataModelScriptDebugBreakpoint | Il provider di script implementa questa interfaccia per esporre la nozione e il controllo di un particolare punto di interruzione all'interno dello script. |
| IDataModelScriptDebugBreakpointEnumerator | Il provider di script implementa questa operazione per enumerare tutti i punti di interruzione che attualmente esistono all'interno dello script (sia abilitati che non). |
Le interfacce di gestione generali sono:
| Interfaccia | Descrizione |
|---|---|
| IDataModelScriptProvider | Interfaccia di base che deve implementare un provider di script. Questa è l'interfaccia registrata con la parte di gestione script della gestione modelli di dati per annunciare il supporto del provider di un determinato tipo di script e registrare su un'estensione di file specifica |
| IDataModelScript | Astrazione di uno script specifico che viene gestito dal provider. Ogni script caricato o modificato ha un'istanza IDataModelScript separata |
| IDataModelScriptClient | Interfaccia client usata dal provider di script per comunicare informazioni a un'interfaccia utente. I provider di script non implementano questa interfaccia. L'applicazione che ospita il modello di dati che desidera usare i provider di script. Un provider di script chiamerà i metodi del client di script per segnalare lo stato, gli errori e così via... |
| IDataModelScriptHostContext | Interfaccia host usata dal provider di script come contenitore per il contenuto dello script. Come il contenuto di una superficie di script diverso dalle manipolazioni eseguite per il modello a oggetti dell'applicazione debugger è fino all'host di debug specifico. Questa interfaccia consente al provider di script di ottenere informazioni su dove posizionarne il contenuto. |
| IDataModelScriptTemplate | I provider di script possono fornire uno o più modelli che fungono da punti di partenza per gli utenti per creare script. Un'applicazione debugger che fornisce un editor predefinito può precompilare nuovi script con contenuto modello come annunciato dal provider tramite questa interfaccia. |
| IDataModelScriptTemplateEnumerator | Interfaccia enumeratore che il provider di script implementa per annunciare tutti i vari modelli supportati. |
| IDataModelNameBinder | Un bindinger dei nomi: un oggetto che può associare un nome in un contesto a un valore. Per un'espressione specificata, ad esempio "foo.bar", un bindinger nome è in grado di associare il nome "bar" nel contesto dell'oggetto "foo" e produrre un valore o un riferimento a esso. I bindinger dei nomi non vengono in genere implementati da un provider di script; invece, il binder predefinito può essere acquisito dal modello di dati e usato dal provider di script. |
Creazione di script debug: IDataModelScriptDebug
Qualsiasi script che è debug indica questa funzionalità tramite la presenza dell'interfaccia IDataModelScriptDebug nello stesso componente che implementa IDataModelScript. La query per questa interfaccia dall'host di debug o dall'applicazione debugger che ospita il modello di dati è ciò che indica la presenza della funzionalità di debug.
L'interfaccia IDataModelScriptDebug è definita come indicato di seguito.
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;
}
Il metodo GetDebugState restituisce lo stato corrente dello script, ad esempio se è in esecuzione o meno. Lo stato viene definito da un valore all'interno dell'enumerazione ScriptDebugState.
Il metodo GetCurrentPosition restituisce la posizione corrente all'interno dello script. Questo può essere chiamato solo quando lo script viene interrotto nel debugger in cui una chiamata a GetScriptState restituirebbe ScriptDebugBreak. Qualsiasi altra chiamata a questo metodo non è valida e avrà esito negativo.
Il metodo GetStack ottiene lo stack di chiamate corrente nella posizione di interruzione. Questo metodo può essere chiamato solo quando lo script viene suddiviso nel debugger.
Il metodo SetBreakpoint imposta un punto di interruzione all'interno dello script. Si noti che l'implementazione è libera di modificare le posizioni della riga e della colonna inpassed per passare a una posizione di codice appropriata. I numeri di riga e colonna effettivi in cui è stato inserito il punto di interruzione possono essere recuperati dalle chiamate di metodo nell'interfaccia IDataModelScriptDebugBreakpoint restituita.
Ogni punto di interruzione creato all'interno dello script tramite il metodo SetBreakpoint viene assegnato un identificatore univoco (intero senza segno a 64 bit) dall'implementazione. Il metodo FindBreakpointById viene usato per ottenere un'interfaccia al punto di interruzione da un identificatore specificato.
Il metodo EnumerateBreakpoints restituisce un enumeratore in grado di enumerare ogni punto di interruzione impostato all'interno di uno script specifico.
Il metodo GetEventFilter restituisce se "break on event" è abilitato per un evento specifico. Gli eventi che possono causare l'interruzione dell'evento sono descritti da un membro dell'enumerazione ScriptDebugEventFilter.
Il metodo SetEventFilter modifica il comportamento "break on event" per un evento specifico come definito da un membro dell'enumerazione ScriptDebugEventFilter. È possibile trovare un elenco completo di eventi disponibili (e una descrizione di questa enumerazione) nella documentazione del metodo GetEventFilter.
Il metodo StartDebugging "attiva" il debugger per uno script specifico. L'azione di avvio del debug non causa attivamente alcuna interruzione o passaggio di esecuzione. Rende semplicemente possibile il debug dello script e fornisce un set di interfacce per il client per comunicare con l'interfaccia di debug.
Il metodo StopDebugging viene chiamato da un client che vuole arrestare il debug. Questa chiamata al metodo può essere eseguita in qualsiasi momento dopo l'esecuzione di StartDebugging (ad esempio: durante un'interruzione, mentre lo script viene eseguito e così via). La chiamata termina immediatamente tutte le attività di debug e reimposta lo stato in prima della chiamata di StartDebugging.
Interfaccia di debug: IDataModelScriptDebugClient
L'host di debug o l'applicazione debugger che desidera fornire un'interfaccia per il debug di script deve fornire un'implementazione dell'interfaccia IDataModelScriptDebugClient al debugger di script tramite il metodo StartDebugging nell'interfaccia di debug per lo script.
IDataModelScriptDebugClient è il canale di comunicazione in cui vengono passati gli eventi di debug e il controllo passa dal motore di esecuzione dello script a un'interfaccia del debugger. È definito come segue.
DECLARE_INTERFACE_(IDataModelScriptDebugClient, IUnknown)
{
STDMETHOD(NotifyDebugEvent)(_In_ ScriptDebugEventInformation *pEventInfo, _In_ IDataModelScript *pScript, _In_opt_ IModelObject *pEventDataObject, _Inout_ ScriptExecutionKind *resumeEventKind) PURE;
}
Ogni volta che si verifica un evento che si interrompe nel debugger dello script, il codice di debug stesso effettua una chiamata all'interfaccia tramite il metodo NotifyDebugEvent. Questo metodo è asincrono. Nessuna esecuzione dello script riprenderà fino a quando l'interfaccia non viene restituita dall'evento. La definizione del debugger di script è progettata per essere semplice: non sono presenti eventi annidati che richiedono l'elaborazione. Un evento di debug viene definito da un record variant noto come ScriptDebugEventInformation. I campi delle informazioni sugli eventi sono validi in gran parte definiti dal membro DebugEvent. Definisce il tipo di evento che si è verificato come descritto da un membro dell'enumerazione ScriptDebugEvent.
Stack di chiamate: IDataModelScriptDebugStack
Quando si verifica un evento che si interrompe nel debugger dello script, l'interfaccia di debug vuole recuperare lo stack di chiamate per il percorso di interruzione. Questa operazione viene eseguita tramite il metodo GetStack. Tale stack viene espresso tramite IDataModelScriptDebugStack definito come indicato di seguito.
Si noti che lo stack complessivo può estendersi su più script e/o più provider di script. Lo stack di chiamate restituito da una singola chiamata al metodo GetStack nell'interfaccia di debug di uno script specifico deve restituire solo il segmento dello stack di chiamate entro i limiti di tale script. È completamente possibile che un motore di debug di script possa recuperare lo stack di chiamate come si estende su più contesti di script se due script dello stesso provider interagiscono. Il metodo GetStack non deve restituire la parte dello stack che si trova in un altro script. Se invece questa situazione può essere rilevata, il frame dello stack che è il frame di limite nello script deve contrassegnare se stesso come frame di transizione tramite un'implementazione dei metodi IsTransitionPoint e GetTransition in tale frame stack. Si prevede che l'interfaccia del debugger unisce lo stack complessivo da più segmenti di stack esistenti.
È imperativo che le transizioni vengano implementate in questo modo o che l'interfaccia di debug possa indirizzare richieste su variabili locali, parametri, punti di interruzione e altri costrutti specifici dello script nel contesto dello script errato! Ciò comporterà un comportamento non definito nell'interfaccia del debugger.
DECLARE_INTERFACE_(IDataModelScriptDebugStack, IUnknown)
{
STDMETHOD_(ULONG64, GetFrameCount)() PURE;
STDMETHOD(GetStackFrame)(_In_ ULONG64 frameNumber, _COM_Outptr_ IDataModelScriptDebugStackFrame **stackFrame) PURE;
}
Il metodo GetFrameCount restituisce il numero di frame dello stack in questo segmento dello stack di chiamate. Se il provider può rilevare fotogrammi in contesti di script diversi o di provider diversi, deve indicare questa operazione al chiamante tramite l'implementazione dei metodi IsTransitionPoint e GetTransition nel frame di ingresso in questo segmento di stack.
GetStackFrame ottiene un particolare frame dello stack dal segmento dello stack. Lo stack di chiamate ha un sistema di indicizzazione in base zero: il frame dello stack corrente in cui si è verificato l'evento di interruzione è frame 0. Il chiamante del metodo corrente è frame 1 (e così via).
Analisi dello stato durante l'interruzione: IDataModelScriptDebugStackFrame
Un particolare frame dello stack di chiamate quando si esegue l'interruzione nel debugger di script può essere recuperato tramite una chiamata al metodo GetStackFrame nell'interfaccia IDataModelScriptDebugStack che rappresenta il segmento dello stack in cui si è verificata l'interruzione. L'interfaccia IDataModelScriptDebugStackFrame restituita per rappresentare questo frame viene definita come indicato di seguito.
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;
}
Il metodo GetName restituisce il nome visualizzato (ad esempio: nome della funzione) di questo frame. Tale nome verrà visualizzato all'interno dello stack backtrace presentato all'utente nell'interfaccia del debugger.
Il metodo GetPosition restituisce la posizione all'interno dello script rappresentato dal frame dello stack. Questo metodo può essere chiamato solo quando lo script si trova all'interno di un'interruzione rappresentata dallo stack in cui è contenuto questo frame. La posizione della riga e della colonna all'interno di questa cornice viene sempre restituita. Se il debugger è in grado di restituire l'intervallo della "posizione di esecuzione" all'interno dello script, è possibile restituire una posizione finale nell'argomento positionSpanEnd. Se il debugger non è in grado di eseguire questa operazione, i valori di riga e colonna nell'estremità di intervallo (se richiesto) devono essere impostati su zero.
L'interfaccia IDataModelScriptDebugStack rappresenta un segmento di uno stack di chiamate, ovvero quella parte dello stack di chiamate contenuta nel contesto di uno script. Se il debugger è in grado di rilevare la transizione da uno script a un altro (o da un provider di script a un altro), può indicare questa situazione implementando il metodo IsTransitionPoint e restituendo true o false in base alle esigenze. Lo stack frame di chiamate che ha immesso lo script in cui si applica il segmento deve essere considerato un punto di transizione. Tutti gli altri fotogrammi non sono.
Se un determinato stack frame è un punto di transizione determinato dal metodo IsTransition (vedere la documentazione relativa a una definizione di punti di transizione), il metodo GetTransition restituisce informazioni sulla transizione. In particolare, questo metodo restituisce lo script precedente, ovvero quello che ha effettuato una chiamata allo script rappresentato dal segmento dello stack contenente questo IDataModelScriptDebugStackFrame.
Il metodo Evaluate valuta un'espressione (del linguaggio del provider di script) nel contesto dello stack frame rappresentato dall'interfaccia IDataModelScriptDebugStackFrame in cui è stato chiamato questo metodo. Il risultato della valutazione dell'espressione deve essere sottoposto a marshalling dal provider di script come IModelObject. Le proprietà e altri costrutti nell'oggetto IModelObject risultante devono essere tutti in grado di essere acquisiti mentre il debugger si trova in uno stato di interruzione.
Il metodo EnumerateLocals restituisce un set di variabili (rappresentato da un'interfaccia IDataModelScriptDebugVariableSetEnumerator) per tutte le variabili locali che si trovano nell'ambito nel contesto dello stack frame rappresentato dall'interfaccia IDataModelScriptDebugStackFrame su cui è stato chiamato questo metodo.
Il metodo EnumerateArguments restituisce un set di variabili (rappresentato da un'interfaccia IDataModelScriptDebugVariableSetEnumerator) per tutti gli argomenti della funzione chiamata nel frame dello stack rappresentato dall'interfaccia IDataModelScriptDebugStackFrame su cui è stato chiamato questo metodo.
Analisi delle variabili: IDataModelScriptDebugVariableSetEnumerator
Un set di variabili nello script di cui viene eseguito il debug (se quelli in un determinato ambito, le variabili locali di una funzione, gli argomenti di una funzione e così via...) sono rappresentati da un set di variabili definito tramite l'interfaccia 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;
}
Il metodo Reset reimposta la posizione dell'enumeratore in cui era immediatamente dopo la creazione, ovvero prima del primo elemento del set.
Il metodo GetNext sposta l'enumeratore nella variabile successiva nel set e restituisce il nome, il valore e tutti i metadati associati alla variabile. Se l'enumeratore ha raggiunto la fine del set, viene restituito l'errore E_BOUNDS. Dopo che il marcatore E_BOUNDS è stato restituito dal metodo GetNext, continuerà a produrre E_BOUNDS quando viene chiamato di nuovo, a meno che non venga effettuata una chiamata Reset in caso di intervento.
Punti di interruzione: IDataModelScriptDebugBreakpoint
I punti di interruzione dello script vengono impostati tramite il metodo SetBreakpoint nell'interfaccia di debug di uno script specificato. Tali punti di interruzione sono rappresentati sia da un ID univoco che da un'implementazione dell'interfaccia IDataModelScriptDebugBreakpoint definita come segue.
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;
}
Il metodo GetId restituisce l'identificatore univoco assegnato dal motore di debug del provider di script al punto di interruzione. Questo identificatore deve essere univoco all'interno del contesto dello script contenitore. L'identificatore del punto di interruzione può essere univoco per il provider; ciò non è tuttavia necessario.
Il metodo IsEnabled restituisce se il punto di interruzione è abilitato o meno. Esiste ancora un punto di interruzione disabilitato ed è ancora nell'elenco dei punti di interruzione per lo script, ma è semplicemente "disattivato" temporaneamente. Tutti i punti di interruzione devono essere creati nello stato abilitato.
Il metodo Enable abilita il punto di interruzione. Se il punto di interruzione è stato disabilitato, "raggiungere il punto di interruzione" dopo la chiamata a questo metodo causerà un'interruzione nel debugger.
Il metodo Disable disabilita il punto di interruzione. Dopo questa chiamata, "raggiungere il punto di interruzione" dopo aver chiamato questo metodo non si interromperà nel debugger. Il punto di interruzione, mentre è ancora presente, viene considerato "disattivato".
Il metodo Remove rimuove il punto di interruzione dall'elenco che lo contiene. Il punto di interruzione non esiste più semanticamente dopo la restituzione di questo metodo. L'interfaccia IDataModelScriptDebugBreakpoint che rappresenta il punto di interruzione viene considerata orfana dopo la chiamata. Nessun altro elemento può (legalmente) essere eseguito con esso dopo questa chiamata diversa dal rilascio.
Il metodo GetPosition restituisce la posizione del punto di interruzione all'interno dello script. Il debugger dello script deve restituire la riga e la colonna all'interno del codice sorgente in cui si trova il punto di interruzione. Se è in grado di farlo, può anche restituire un intervallo di origine rappresentato dal punto di interruzione compilando una posizione finale come definito dall'argomento positionSpanEnd. Se il debugger non è in grado di produrre questo intervallo e il chiamante lo richiede, i campi Riga e Colonna della posizione finale dell'intervallo devono essere compilati come zero che indica che non è possibile specificare i valori.
Enumerazione punto di interruzione: IDataModelScriptDebugBreakpointEnumerator
Se un provider di script supporta il debug, deve anche tenere traccia di tutti i punti di interruzione associati a ogni script ed essere in grado di enumerare tali punti di interruzione nell'interfaccia di debug. L'enumeratore per i punti di interruzione viene acquisito tramite il metodo EnumerateBreakpoints nell'interfaccia di debug per uno script specificato ed è definito come segue.
DECLARE_INTERFACE_(IDataModelScriptDebugBreakpointEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptDebugBreakpoint **breakpoint) PURE;
}
Il metodo Reset reimposta la posizione dell'enumeratore in cui era appena dopo la creazione dell'enumeratore, ovvero prima del primo punto di interruzione enumerato.
Il metodo GetNext sposta l'enumeratore in avanti al punto di interruzione successivo da enumerare e restituisce l'interfaccia IDataModelScriptDebugBreakpoint per tale punto di interruzione. Se l'enumeratore ha raggiunto la fine dell'enumerazione, restituisce E_BOUNDS. Dopo aver generato l'errore di E_BOUNDS, le chiamate successive al metodo GetNext continueranno a produrre E_BOUNDS a meno che non sia stata effettuata una chiamata al metodo Reset.
Vedere anche
Questo argomento fa parte di una serie che descrive le interfacce accessibili da C++, come usarle per compilare un'estensione del debugger basata su C++ e come usare altri costrutti di modelli di dati (ad esempio JavaScript o NatVis) da un'estensione del modello di dati C++.
Panoramica del modello di dati del debugger C++
Interfacce C++ del modello di dati del debugger
Oggetti C++ del modello di dati del debugger
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per