Interfaces adicionais do Modelo de Dados do Depurador C++
Este tópico descreve algumas interfaces adicionais associadas ao modelo de dados C++ do Depurador, como metadados, conceitos e enumeração de objetos.
Interfaces de metadados do modelo de dados do depurador
Uma das noções principais no modelo de dados é que um objeto (particularmente um sintético) é um dicionário de tuplas de chave/valor/metadados. Cada chave pode ter um armazenamento inteiro de metadados associado a ela que descreve uma variedade de coisas em torno da chave e seu valor potencial. Observe que os metadados não alteram, de forma alguma, o valor da chave. São apenas informações auxiliares associadas à chave e seu valor que podem afetar a apresentação ou outros atributos associados da chave e seu valor.
Em alguns sentidos, um repositório de metadados não é tão diferente das tuplas de chave/valor/metadados, que são a essência de um objeto no modelo de dados. Ele é, no entanto, simplificado a partir dessa visão. Um repositório de metadados é representado pela interface IKeyStore. Embora também seja uma coleção de tuplas de chave/valor/metadados, há limitações para o que pode ser feito com um armazenamento de chaves de metadados versus um objeto de modelo:
- Um repositório de chaves só pode ter um repositório pai -- ele não pode ter uma cadeia arbitrária de modelos pai.
- Um repositório de chaves não tem conceitos. Ele só pode ter o dicionário de tuplas de chave/valor/metadados. Isso significa que as chaves presentes em um repositório de chaves são estáticas. Eles não podem ser criados sob demanda por um sistema de linguagem dinâmico.
- Somente por convenção, os valores em um repositório de chaves definido por metadados são restritos a valores básicos (intrínsecos e acessadores de propriedades)
Embora um repositório de chaves possa ter um número arbitrário (e nomenclatura arbitrária) de chaves, há determinados nomes que têm valores semânticos definidos. Atualmente, esses nomes são:
| Nome da chave | Tipo de valor | Descrição |
|---|---|---|
| PreferredRadix | Inteiro: 2, 8, 10 ou 16 | Indica em qual base um valor ordinal deve ser exibido |
| PreferredFormat | Inteiro: conforme definido pela enumeração PreferredFormat | Indica o tipo de formatação preferencial para exibição do valor |
| PreferredLength | Inteiro | Para arrays e outros contêineres, indica quantos elementos devem ser exibidos por padrão |
| FindDerivation | Booliano | Indica se o host de depuração deve executar a análise de tipo derivado no valor antes de usar (por exemplo: exibição) |
| Ajuda | String | Texto de ajuda em estilo de dica de ferramenta para a chave que pode ser apresentado pela interface do usuário de maneira apropriadamente útil. |
| ActionName | String | Indica que o método fornecido (aquele que não usa argumentos e não retorna valores) é uma ação. O nome da ação é especificado em metadados. Uma interface de usuário pode utilizar esse nome para apresentar a opção em um menu de contexto ou outra interface apropriada |
| ActionIsDefault | Booliano | Válido somente se a chave ActionName for especificada, indica que essa é a ação padrão para o objeto. |
| ActionDescription | String | Válido somente se a chave ActionName for especificada, fornece uma descrição em estilo de dica de ferramenta para a ação. Esse texto pode ser apresentado pela interface do usuário de maneira apropriadamente útil. |
Observe que, embora as chaves no repositório de metadados possam ter seus próprios metadados (ad infiniteum), atualmente não há utilização para tal. A maioria dos chamadores especificará null para todos os parâmetros de metadados em métodos na interface IKeyStore.
A interface de metadados principal: IKeyStore
A interface IKeyStore é definida assim:
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;
}
O método GetKey é análogo ao método GetKey em IModelObject. Ele retornará o valor da chave especificada se ela existir no repositório de chaves ou em seu repositório pai. Observe que, se o valor da chave for um acessador de propriedade, o método GetValue não será chamado nele. O IModelPropertyAccessor real que acompanha um IModelObject será retornado. É comum que um cliente chame GetKeyValue por esse motivo.
O método SetKey é análogo ao método SetKey em IModelObject. É o único método capaz de criar uma chave e associar metadados a ela no repositório de chaves.
O método GetKeyValue é o primeiro método que um cliente usará para localizar o valor de uma chave específica no repositório de metadados. Se a chave especificada pelo argumento de chave existir no repositório (ou em seu repositório pai), seu valor e todos os metadados associados a ela serão retornados. Se o valor da chave for um acessador de propriedade (um IModelPropertyAccessor que acompanha um IModelObject), o método GetValue do acessador de propriedade será chamado automaticamente por GetKeyValue e o valor subjacente da propriedade retornado.
O método SetKeyValue é análogo ao método SetKeyValue em IModelObject. Esse método não é capaz de criar uma chave no repositório de metadados. Se existir uma chave, como indicado pelo argumento de chave, seu valor será definido conforme indicado. Se a chave for um acessador de propriedade, o método SetValue será chamado nele para definir o valor subjacente. Observe que os metadados normalmente ficam estáticos depois de criados. O uso desse método em um repositório de chaves de metadados deve ser pouco frequente.
O método ClearKeys é análogo ao método ClearKeys em IModelObject. Ele remove todas as chaves do repositório de metadados fornecido. Esse método não tem efeito em nenhum repositório pai.
Enumeração de objeto no modelo de dados
Enumerar objetos no modelo de dados
Há duas interfaces principais de enumeração de chave no modelo de dados: IKeyEnumerator e IRawEnumerator. Embora essas sejam as duas interfaces principais, elas podem ser usadas para enumerar objetos em um dos três estilos:
Chaves – a interface IKeyEnumerator pode ser adquirida por meio de uma chamada para EnumerateKeys para enumerar as chaves de um objeto e seus valores/metadados sem resolver nenhum acessador de propriedade subjacente. Esse estilo de enumeração pode retornar valores brutos de IModelPropertyAccessor que acompanham IModelObjects.
Valores – as interfaces IKeyEnumerator e IRawEnumerator podem ser adquiridas por meio de chamadas para EnumerateKeyValues ou EnumerateRawValues para enumerar as chaves/valores brutos em um objeto e seus valores/metadados. Todos os acessadores de propriedade presentes na enumeração são resolvidos automaticamente por meio de uma chamada para o método GetValue subjacente durante essa enumeração.
Referências – as interfaces IKeyEnumerator e IRawEnumerator podem ser adquiridas por meio de chamadas para EnumerateKeyReferences ou EnumerateRawReferences para enumerar referências a chaves/valores brutos em um objeto. Essas referências podem ser salvas e, posteriormente, usadas para obter ou definir a chave subjacente ou o valor bruto.
KeyEnumerator: Enumeração de chaves sintéticas
A interface IKeyEnumerator é única para a enumeração de todas as chaves (por chave, valor ou referência) dentro de um objeto de instância e todos os modelos pai associados em sua cadeia de modelos pai. A interface é definida assim:
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;
}
O método Reset redefine o enumerador para a posição em que estava quando foi adquirido pela primeira vez (por exemplo: antes do primeiro elemento na enumeração). Uma chamada subsequente para GetNext retornará a primeira chave enumerada.
O método GetNext avança o enumerador e retorna a chave nessa posição na enumeração.
IRawEnumerator: Enumeração de construções de linguagem nativa ou subjacente (C/C++)
A interface IRawEnumerator é única para a enumeração de todas as construções nativas/de linguagem (por valor ou referência) dentro de um objeto que representa uma construção nativa dentro do espaço de endereço do destino de depuração. A interface é definida assim:
DECLARE_INTERFACE_(IRawEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_opt_ BSTR* name, _Out_opt_ SymbolKind *kind, _COM_Errorptr_opt_ IModelObject** value) PURE;
}
O método Reset redefine o enumerador para a posição em que estava quando foi adquirido pela primeira vez (por exemplo: antes do primeiro elemento na enumeração). Uma chamada subsequente para GetNext retornará a primeira construção nativa/de linguagem enumerada.
O método GetNext avança o enumerador e retorna a construção nativa/de linguagem nessa posição na enumeração.
Consulte também
Este tópico faz parte de uma série que descreve as interfaces acessíveis a partir de C++, como usá-las para criar uma extensão de depurador baseada em C++ e como fazer uso de outras construções de modelo de dados (por exemplo: JavaScript ou NatVis) a partir de uma extensão de modelo de dados C++.
Visão geral do Modelo de Dados do Depurador C++
Interfaces do Modelo de Dados do Depurador C++
Objetos do Modelo de Dados do Depurador C++
Interfaces adicionais do Modelo de Dados do Depurador C++