Condividi tramite


Interfacce aggiuntive del modello di dati del debugger C++

In questo argomento vengono descritte alcune interfacce aggiuntive associate al modello di dati C++ debugger, ad esempio metadati, concetti ed enumerazione di oggetti.

Interfacce dei metadati del modello di dati del debugger

Una delle nozioni di base nel modello di dati è che un oggetto (in particolare uno sintetico) è un dizionario di tuple chiave/valore/metadati. A ogni chiave può essere associato un intero archivio di metadati che descrive un'ampia gamma di elementi che circondano la chiave e il relativo valore potenziale. Si noti che i metadati non modificano in alcun modo il valore della chiave. Si tratta solo di informazioni ausiliarie associate alla chiave e al relativo valore che possono influire sulla presentazione o su altri attributi associati della chiave e del relativo valore.

In alcuni sensi, un archivio di metadati non è tutto diverso dalle tuple chiave/valore/metadati che sono l'essenza di un oggetto nel modello di dati. Tuttavia, è semplificato da questa visualizzazione. Un archivio metadati è rappresentato dall'interfaccia IKeyStore. Anche se una raccolta di tuple chiave/valore/metadati, esistono limitazioni a ciò che è possibile eseguire con un archivio chiavi di metadati rispetto a un oggetto modello:

  • Un archivio chiavi può avere un solo archivio padre. Non può avere una catena arbitraria di modelli padre.
  • Un archivio chiavi non ha concetti. Può avere solo il dizionario di tuple chiave/valore/metadati. Ciò significa che le chiavi presenti in un archivio chiavi sono statiche. Non possono essere creati su richiesta da un sistema linguistico dinamico.
  • Solo per convenzione, i valori in un archivio chiavi definito dai metadati sono limitati ai valori di base (funzioni di accesso intrinseche e proprietà)

Anche se un archivio chiavi può avere un numero arbitrario (e un nome arbitrario) di chiavi, esistono alcuni nomi con valori semantici definiti. Attualmente, questi nomi sono:

Nome chiave Tipo di valore Descrizione
PreferredRadix Intero: 2, 8, 10 o 16 Indica il radix in cui deve essere visualizzato un valore ordinale
PreferredFormat Integer: come definito dall'enumerazione PreferredFormat Indica il tipo di formattazione preferito per la visualizzazione del valore
PreferredLength Intero Per matrici e altri contenitori, indica quanti elementi devono essere visualizzati per impostazione predefinita
FindDerivation Booleano Indica se l'host di debug deve eseguire l'analisi dei tipi derivati sul valore prima di usare (ad esempio: visualizzazione)
Help String Testo della Guida della descrizione comando per la chiave che può essere presentato dall'interfaccia utente in modo appropriato.
ActionName String Indica che il metodo specificato (uno che non accetta argomenti e non restituisce valori) è un'azione. Il nome dell'azione viene specificato nei metadati. Un'interfaccia utente può utilizzare questo nome per presentare l'opzione in un menu di scelta rapida o in un'altra interfaccia appropriata
ActionIsDefault Booleano Valido solo se viene specificata la chiave ActionName, indica che si tratta dell'azione predefinita per l'oggetto.
ActionDescription String Valido solo se viene specificata la chiave ActionName, fornisce una descrizione dello stile della descrizione comando per l'azione. Tale testo può essere presentato dall'interfaccia utente in modo appropriato.

Si noti che mentre le chiavi nell'archivio di metadati possono avere metadati propri (ad infiniteum), attualmente non è disponibile alcun uso per tali metadati. La maggior parte dei chiamanti specifica null per tutti i parametri di metadati nei metodi nell'interfaccia IKeyStore.

Interfaccia dei metadati di base: IKeyStore

L'interfaccia IKeyStore è definita come segue:

DECLARE_INTERFACE_(IKeyStore, IUnknown)
{
   STDMETHOD(GetKey)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
   STDMETHOD(SetKey)(_In_ PCWSTR key, _In_opt_ IModelObject* object, _In_opt_ IKeyStore* metadata) PURE;
   STDMETHOD(GetKeyValue)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
   STDMETHOD(SetKeyValue)(_In_ PCWSTR key, _In_ IModelObject* object) PURE;
   STDMETHOD(ClearKeys)() PURE;
}

GetKey

Il metodo GetKey è analogo al metodo GetKey in IModelObject. Restituisce il valore della chiave specificata, se presente nell'archivio chiavi o nell'archivio chiavi padre dell'archivio chiavi. Si noti che se il valore della chiave è una funzione di accesso alla proprietà, il metodo GetValue non verrà chiamato nella funzione di accesso della proprietà. Verrà restituito il valore IModelPropertyAccessor effettivo in un oggetto IModelObject. In genere un client chiamerà GetKeyValue per questo motivo.

SetKey

Il metodo SetKey è analogo al metodo SetKey in IModelObject. È l'unico metodo in grado di creare una chiave e associarne i metadati all'interno dell'archivio chiavi.

GetKeyValue

Il metodo GetKeyValue è il primo metodo a cui un client passerà per trovare il valore di una determinata chiave all'interno dell'archivio metadati. Se la chiave specificata dall'argomento chiave esiste all'interno dell'archivio (o dell'archivio padre), verrà restituito il valore di tale chiave e tutti i metadati associati. Se il valore della chiave è una funzione di accesso alla proprietà (un oggetto IModelPropertyAccessor sottoposto a boxing in un oggetto IModelObject), il metodo GetValue della funzione di accesso della proprietà verrà chiamato automaticamente da GetKeyValue e dal valore sottostante della proprietà restituita.

SetKeyValue

Il metodo SetKeyValue è analogo al metodo SetKeyValue in IModelObject. Questo metodo non è in grado di creare una nuova chiave all'interno dell'archivio metadati. Se è presente una chiave esistente come indicato dall'argomento chiave, il relativo valore verrà impostato come indicato. Se la chiave è una funzione di accesso alla proprietà, il metodo SetValue verrà chiamato sulla funzione di accesso della proprietà per impostare il valore sottostante. Si noti che i metadati sono in genere statici dopo la creazione. L'uso di questo metodo in un archivio chiavi di metadati deve essere poco frequente.

ClearKeys

Il metodo ClearKeys è analogo al metodo ClearKeys in IModelObject. Rimuoverà ogni chiave dall'archivio di metadati specificato. Questo metodo non ha alcun effetto su alcun archivio padre.

Enumerazione oggetto nel modello di dati

Enumerazione di oggetti nel modello di dati

Esistono due interfacce di enumerazione chiave di base nel modello di dati: IKeyEnumerator e IRawEnumerator. Anche se si tratta delle due interfacce principali, possono essere usate per enumerare gli oggetti in uno dei tre stili seguenti:

Keys : l'interfaccia IKeyEnumerator può essere acquisita tramite una chiamata a EnumerateKeys per enumerare le chiavi di un oggetto e i relativi valori/metadati senza risolvere le funzioni di accesso alle proprietà sottostanti. Questo stile di enumerazione può restituire valori IModelPropertyAccessor non elaborati boxed in IModelObjects.

Valori : le interfacce IKeyEnumerator e IRawEnumerator possono essere acquisite tramite chiamate a EnumerateKeyValues o EnumerateRawValues per enumerare le chiavi/valori non elaborati in un oggetto e i relativi valori/metadati. Tutte le funzioni di accesso alle proprietà presenti nell'enumerazione vengono risolte automaticamente tramite una chiamata al metodo GetValue sottostante durante tale enumerazione.

Riferimenti : le interfacce IKeyEnumerator e IRawEnumerator possono essere acquisite tramite chiamate a EnumerateKeyReferences o EnumerateRawReferences per enumerare riferimenti ai valori chiavi/non elaborati in un oggetto. Tali riferimenti possono essere salvati e usati in un secondo momento per ottenere o impostare la chiave sottostante o il valore non elaborato.

KeyEnumerator: enumerazione di chiavi sintetiche

L'interfaccia IKeyEnumerator è la singola interfaccia per l'enumerazione di tutte le chiavi (per chiave, valore o riferimento) all'interno di un oggetto istanza e di tutti i modelli padre associati nella catena di modelli padre. L'interfaccia viene definita come segue:

DECLARE_INTERFACE_(IKeyEnumerator, IUnknown)
{
    STDMETHOD(Reset)() PURE;
    STDMETHOD(GetNext)(_Out_ BSTR* key, _COM_Errorptr_opt_ IModelObject** value, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
}

Reimposta

Il metodo Reset reimposta l'enumeratore sulla posizione in cui si trovava alla prima acquisizione, ad esempio prima del primo elemento dell'enumerazione. Una chiamata successiva a GetNext restituirà la prima chiave enumerata.

GetNext

Il metodo GetNext sposta l'enumeratore in avanti e restituisce la chiave in tale posizione nell'enumerazione .

IRawEnumerator: enumerazione di costrutti di linguaggio nativo o sottostante (C/C++)

L'interfaccia IRawEnumerator è la singola interfaccia per l'enumerazione di tutti i costrutti nativi/linguistici (per valore o riferimento) all'interno di un oggetto che rappresenta un costrutto nativo all'interno dello spazio indirizzi della destinazione di debug. L'interfaccia viene definita come segue:

DECLARE_INTERFACE_(IRawEnumerator, IUnknown)
{
    STDMETHOD(Reset)() PURE;
    STDMETHOD(GetNext)(_Out_opt_ BSTR* name, _Out_opt_ SymbolKind *kind, _COM_Errorptr_opt_ IModelObject** value) PURE;
}

Reimposta

Il metodo Reset reimposta l'enumeratore sulla posizione in cui si trovava alla prima acquisizione, ad esempio prima del primo elemento dell'enumerazione. Una chiamata successiva a GetNext restituirà il primo costrutto nativo/linguaggio enumerato.

GetNext

Il metodo GetNext sposta l'enumeratore in avanti e restituisce il costrutto nativo/lingua in tale posizione nell'enumerazione .


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

Interfacce aggiuntive del modello di dati del debugger C++

Concetti relativi al modello di dati del debugger C++

Scripting C++ del modello di dati del debugger