Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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 Data Model Manager, 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") che vengono gestiti dal provider consentendo 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.
Core Script Manager: IDataModelScriptManager
L'interfaccia di gestione script di base è 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 dei 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 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 collegare un nuovo linguaggio al modello di dati. Quando questo metodo viene chiamato, lo script manager richiama immediatamente il provider di script specificato e chiede 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 avere ancora riferimenti allo script. Possono essere presenti modelli di dati, metodi o oggetti che fanno riferimento direttamente ai costrutti nello script. Un provider di script deve essere preparato per gestirlo.
Il metodo FindProviderForScriptType cerca nel gestore script un provider con una stringa di tipo script, come indicato in questo metodo. Se non è possibile trovarne uno, questo metodo avrà esito negativo; in caso contrario, tale provider di script verrà restituito al chiamante.
EnumerateScriptProviders
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 del provider di 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 in avanti un elemento e restituisce il provider di script che si trova in tale elemento. Quando l'enumeratore raggiunge la fine dell'enumerazione, verrà restituito E_BOUNDS. La chiamata al metodo GetNext dopo la ricezione di questo errore continuerà a restituire E_BOUNDS a tempo indeterminato.
interfacce host C++ del debugger per lo scripting
il ruolo dell'host in 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 la creazione di script. Tali elementi vengono lasciati all'applicazione debugger complessiva o alle estensioni che forniscono queste funzionalità. Vi è 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 da 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. Il modo in cui il contenuto di una superficie di script diversa dalle manipolazioni eseguite per il modello a oggetti dell'applicazione debugger dipende dall'host di debug specifico. Questa interfaccia consente al provider di script di ottenere informazioni sulla posizione in cui posizionarne il contenuto. Per altre informazioni, vedere interfacce di scripting C++ del modello di dati C++ 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, ad esempio, possono 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 debugger 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. Durante l'inizializzazione, un provider di script si registra con la parte 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. Si collega tra gli script scritti nel linguaggio JavaScript e il modello di dati, consentendo forme arbitrarie di controllo del debugger ed estendibilità.
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 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 di base che deve essere implementata da un provider di script. 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 la registrazione in 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 utilizzata 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 vuole 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. Il modo in cui il contenuto di una superficie di script diversa dalle manipolazioni eseguite per il modello a oggetti dell'applicazione debugger dipende dall'host di debug specifico. Questa interfaccia consente al provider di script di ottenere informazioni sulla posizione in cui posizionarne il contenuto. |
| IDataModelScriptTemplate | I provider di script possono fornire uno o più modelli che fungono da punti di partenza per consentire agli utenti di 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 dell'enumeratore implementata dal provider di script per annunciare tutti i vari modelli supportati. |
| IDataModelNameBinder | Gestore di associazione dei nomi: un oggetto che può associare un nome in un contesto a un valore. Per una determinata espressione, ad esempio "foo.bar", un gestore di associazione dei nomi è in grado di associare il nome "bar" nel contesto dell'oggetto "foo" e produrre un valore o un riferimento. I binder 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 essere QueryInterface per IDataModelScriptDebug se lo script è debugbile. |
| 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 opzione per enumerare tutti i punti di interruzione attualmente presenti all'interno dello script (se abilitati o meno). |
il 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 di gestione script del gestore 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) gestito 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". È probabile che la stringa restituita venga 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 di file per gli script gestiti da questo provider (senza il punto) come stringa allocata tramite il metodo SysAllocString. L'applicazione debugger che ospita il modello di dati (con supporto di scripting) 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. Si tratta di contenuto che il provider di script desidera prepopolato 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 è ciò 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 di 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 desidera creare un nuovo script vuoto e chiama il metodo CreateScript su 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 entrambi un tipo o un concetto (ad esempio, la nozione del debugger di che cos'è un processo). Entrambi gli script possono 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 valore BSTR null. Non dovrebbe fallire in questa circostanza. Se lo script viene rinominato in modo esplicito tramite una chiamata al metodo Rename, il metodo GetName deve restituire il nome appena assegnato.
Il metodo Rename assegna un nuovo nome allo script. È responsabilità dell'implementazione dello script salvare questo nome e restituirlo a qualsiasi chiamata al metodo GetName. Questa operazione viene spesso chiamata quando un'interfaccia utente sceglie salva con nome nello script in un nuovo nome. Si noti che la ridenominazione dello script può influire sulla posizione in cui l'applicazione host sceglie di proiettare il contenuto dello script.
Il metodo Populate viene chiamato dal client per modificare o sincronizzare il "contenuto" dello script. Si tratta della notifica inviata 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 modificati dallo script. Si tratta semplicemente di una notifica al provider di script che il contenuto dello script è stato modificato in modo che possa sincronizzare il proprio stato interno.
Il metodo Execute esegue il contenuto dello script in base all'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" immaginario in un'interfaccia utente, tale "funzione principale" non viene chiamata durante un'operazione Di esecuzione. L'operazione Execute può essere considerata solo per eseguire operazioni di inizializzazione e modifica del modello a oggetti , ad esempio l'esecuzione del codice radice e la configurazione di punti di estendibilità.
Il metodo Unlink annulla l'operazione Execute. Eventuali manipolazioni o punti di estendibilità del modello 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 Execute oppure può essere rilasciato.
Il metodo IsInvocable restituisce se lo script è richiamabile, ovvero se ha una "funzione main" come definito dal linguaggio o dal provider. Una "funzione principale" di questo tipo è concettualmente un elemento 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 true return 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 questa nozione 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.
Il contesto host per uno script: IDataModelScriptHostContext
L'host di debug ha qualche influenza su come e dove proietta il contenuto dello script del modello di dati. È previsto che ogni script richieda all'host un contesto in cui posizionare 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 oggetto 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 informi l'host di debug quando si verificano determinate operazioni 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ò posizionare qualsiasi bridge tra il modello di dati e lo script. È qui, ad esempio, che il provider di script potrebbe inserire oggetti del 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 desiderano 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. Questi 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. Questa operazione potrebbe non riuscire con E_NOTIMPL se il modello non ha un nome. Il singolo modello predefinito (se presente) non è necessario 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 capire cosa è progettato per eseguire il modello. Il modello può restituire E_NOTIMPL da questo metodo se non contiene 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 uno di questi modelli viene fornito, il provider di script deve implementare un enumeratore su di essi che viene restituito in 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 si trovava al momento della creazione, prima del primo modello prodotto.
Il metodo GetNext sposta l'enumeratore nel modello successivo e lo restituisce. Alla fine dell'enumerazione, l'enumeratore restituisce E_BOUNDS. Dopo che il marcatore E_BOUNDS è stato raggiunto, l'enumeratore continuerà a produrre errori E_BOUNDS indefiniti 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. Tale gestore di associazione incapsula un set di regole su come 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 rispetto a un nome nativo (uno nel sistema di tipi del linguaggio di cui viene eseguito il 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 dei 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 sottostante non può usare il valore per eseguire di nuovo 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 di nuovo 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 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 esiste un costo significativamente superiore per l'enumerazione di un oggetto tramite il gestore di associazione dei nomi rispetto alla chiamata dei metodi IModelObject.
Il metodo EnumerateReferences enumera il set di nomi e i riferimenti a essi che verranno associati 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 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 esiste un costo significativamente superiore per l'enumerazione di un oggetto tramite il gestore di associazione dei nomi 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 relativo al 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.
Mentre l'interfaccia IDataModelScriptDebug è il punto di partenza per ottenere l'accesso alle funzionalità di debug di un provider di script, viene unita a un set di altre interfacce per fornire funzionalità di debug complessive.
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 essere QueryInterface per IDataModelScriptDebug se lo script è debugbile. |
| 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 opzione per enumerare tutti i punti di interruzione attualmente presenti all'interno dello script (se abilitati o meno). |
Le interfacce di gestione generali sono:
| Interfaccia | Descrizione |
|---|---|
| IDataModelScriptProvider | Interfaccia di base che deve essere implementata da un provider di script. 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 la registrazione in 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 utilizzata 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 vuole 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. Il modo in cui il contenuto di una superficie di script diversa dalle manipolazioni eseguite per il modello a oggetti dell'applicazione debugger dipende dall'host di debug specifico. Questa interfaccia consente al provider di script di ottenere informazioni sulla posizione in cui posizionarne il contenuto. |
| IDataModelScriptTemplate | I provider di script possono fornire uno o più modelli che fungono da punti di partenza per consentire agli utenti di 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 dell'enumeratore implementata dal provider di script per annunciare tutti i vari modelli supportati. |
| IDataModelNameBinder | Gestore di associazione dei nomi: un oggetto che può associare un nome in un contesto a un valore. Per una determinata espressione, ad esempio "foo.bar", un gestore di associazione dei nomi è in grado di associare il nome "bar" nel contesto dell'oggetto "foo" e produrre un valore o un riferimento. I binder 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. |
Rendere debug degli script: IDataModelScriptDebug
Qualsiasi script di cui è possibile eseguire il 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 segue.
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 è definito da un valore all'interno dell'enumerazione ScriptDebugState.
Il metodo GetCurrentPosition restituisce la posizione corrente all'interno dello script. Questa operazione può essere chiamata solo quando lo script viene suddiviso nel debugger in cui una chiamata a GetScriptState restituirà 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 regolare le posizioni di riga e colonna inpassate per spostarsi in avanti a una posizione del codice appropriata. I numeri di riga e colonna effettivi in cui è stato inserito il punto di interruzione possono essere recuperati dalle chiamate al metodo sull'interfaccia IDataModelScriptDebugBreakpoint restituita.
A 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 determinato evento. Gli eventi che possono causare l'interruzione dell'evento vengono descritti da un membro dell'enumerazione ScriptDebugEventFilter.
Il metodo SetEventFilter modifica il comportamento "break on event" per un determinato evento, come definito da un membro dell'enumerazione ScriptDebugEventFilter. Un elenco completo degli eventi disponibili (e una descrizione di questa enumerazione) sono disponibili nella documentazione relativa al metodo GetEventFilter.
Il metodo StartDebugging "attiva" il debugger per uno script specifico. L'azione di avvio del debug non causa attivamente interruzioni o istruzioni di esecuzione. Rende semplicemente possibile il debug dello script e fornisce un set di interfacce per consentire al client di 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 che StartDebugging è stato effettuato correttamente (ad esempio, durante un'interruzione, durante l'esecuzione dello script e così via). La chiamata interrompe immediatamente tutte le attività di debug e reimposta lo stato su prima della chiamata a StartDebugging.
'interfaccia di debug: IDataModelScriptDebugClient
L'applicazione dell'host di debug o del debugger che vuole fornire un'interfaccia per il debug di script deve fornire un'implementazione dell'interfaccia IDataModelScriptDebugClient al debugger di script tramite il metodo StartDebugging sull'interfaccia di debug per lo script.
IDataModelScriptDebugClient è il canale di comunicazione tra cui vengono passati gli eventi di debug e il controllo passa dal motore di esecuzione dello script a un'interfaccia del debugger. Viene 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 di script, il codice di debug stesso effettua una chiamata all'interfaccia tramite il metodo NotifyDebugEvent. Questo metodo è sincrono. Non verrà ripresa alcuna esecuzione dello script fino a quando l'interfaccia non viene restituita dall'evento. La definizione del debugger di script è progettata per essere semplice: non esistono eventi annidati che richiedono l'elaborazione. Un evento di debug è definito da un record variant noto come ScriptDebugEventInformation. I campi nelle informazioni sugli eventi sono in gran parte definiti dal membro DebugEvent. Definisce il tipo di evento che si è verificato come descritto da un membro dell'enumerazione ScriptDebugEvent.
lo stack di chiamate: IDataModelScriptDebugStack
Quando si verifica un evento che si interrompe nel debugger di 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 su un'interfaccia di debug di uno script specifico deve restituire solo il segmento dello stack di chiamate all'interno dei limiti dello script. È del tutto 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, lo stack frame che rappresenta il frame limite nello script deve contrassegnarsi come frame di transizione tramite un'implementazione dei metodi IsTransitionPoint e GetTransition su tale stack frame. È previsto che l'interfaccia del debugger unisce lo stack complessivo dai più segmenti di stack esistenti.
È fondamentale implementare le transizioni in questo modo o l'interfaccia di debug può indirizzare richieste su variabili locali, parametri, punti di interruzione e altri costrutti specifici dello script al contesto di 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 stack frame in questo segmento dello stack di chiamate. Se il provider può rilevare fotogrammi in contesti di script diversi o di provider diversi, deve indicare questo comportamento al chiamante tramite l'implementazione dei metodi IsTransitionPoint e GetTransition nel frame di ingresso in questo segmento dello stack.
GetStackFrame ottiene un particolare stack frame dal segmento dello stack. Lo stack di chiamate ha un sistema di indicizzazione in base zero: lo stack frame corrente in cui si è verificato l'evento di interruzione è frame 0. Il chiamante del metodo corrente è frame 1 (e così via).
esame dello stato quando si è interrotto: IDataModelScriptDebugStackFrame
Un particolare frame dello stack di chiamate quando si suddivide 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 è definita come segue.
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, il 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à dell'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 un provider di script a un altro), può indicare questa situazione implementando il metodo IsTransitionPoint e restituendo true o false in base alle esigenze. Il frame dello stack 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 per 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 su 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 è in uno stato di interruzione.
Il metodo EnumerateLocals restituisce un set di variabili (rappresentato da un'interfaccia IDataModelScriptDebugVariableSetEnumerator) per tutte le variabili locali incluse nell'ambito nel contesto del frame dello stack 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...) è rappresentato 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 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; tuttavia, questo non è obbligatorio.
Il metodo IsEnabled restituisce se il punto di interruzione è abilitato o meno. Esiste ancora un punto di interruzione disabilitato ed è ancora presente 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 la chiamata a questo metodo non verrà interrotto nel debugger. Il punto di interruzione, 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. Niente altro può (legalmente) essere fatto con esso dopo questa chiamata diversa dal rilascio.
Il metodo GetPosition restituisce la posizione del punto di interruzione all'interno dello script. Il debugger di 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 indicano 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 e di 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. Una volta generato l'errore 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 di C++