Compartilhar via


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 objeto.

Interfaces de metadados do modelo de dados do depurador de

Uma das principais noções no modelo de dados é que um objeto (particularmente um sintético) é um dicionário de tuplas chave/valor/metadados. Cada chave pode ter um repositório 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 chave/valor/metadados que são a essência de um objeto no modelo de dados. No entanto, ele é simplificado nessa exibiçã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 repositório de chaves de metadados versus um objeto de modelo:

  • Um repositório de chaves só pode ter um único 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 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 propriedade)

Embora um repositório de chaves possa ter um número arbitrário (e uma nomenclatura arbitrária) de chaves, há certos 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 radix 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 Número Inteiro Para matrizes 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 fio Texto de ajuda de estilo de dica de ferramenta para a chave que pode ser apresentada pela interface do usuário de maneira adequadamente útil.
ActionName fio Indica que o método fornecido (que não usa argumentos e não retorna valores) é uma ação. O nome da ação é especificado em metadados. Uma interface do 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 fio Válido somente se a chave ActionName for especificada, isso fornecerá uma descrição de estilo de dica de ferramenta para a ação. Esse texto pode ser apresentado pela interface do usuário de maneira adequadamente útil.

Observe que, embora as chaves no repositório de metadados possam ter seus próprios metadados (ad infiniteum), atualmente não há uso para isso. A maioria dos chamadores especificará nulo para quaisquer parâmetros de metadados em métodos na interface IKeyStore.

a interface de metadados principal: IKeyStore

A interface IKeyStore é definida da seguinte maneira:

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

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 no repositório pai do repositório de chaves. Observe que, se o valor da chave for um acessador de propriedade, o método GetValue não será chamado no acessador de propriedade. O IModelPropertyAccessor real em caixa em um IModelObject será retornado. É típico que um cliente chame GetKeyValue por esse motivo.

SetKey

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 dentro do repositório de chaves.

GetKeyValue

O método GetKeyValue é o primeiro método para o qual um cliente irá para localizar o valor de uma chave específica no repositório de metadados. Se a chave especificada pelo argumento chave existir no repositório (ou no repositório pai), o valor dessa chave e os metadados associados a ela serão retornados. Se o valor da chave for um acessador de propriedade (um IModelPropertyAccessor boxed em um IModelObject), o método GetValue do acessador de propriedade será automaticamente chamado por GetKeyValue e o valor subjacente da propriedade retornada.

SetKeyValue

O método SetKeyValue é análogo ao método SetKeyValue em IModelObject. Esse método não é capaz de criar uma nova chave no repositório de metadados. Se houver uma chave existente, conforme indicado pelo argumento chave, seu valor será definido como indicado. Se a chave for um acessador de propriedade, o método SetValue será chamado no acessador de propriedade para definir o valor subjacente. Observe que os metadados normalmente são estáticos uma vez criados. O uso desse método em um repositório de chaves de metadados deve ser pouco frequente.

ClearKeys

O método ClearKeys é análogo ao método ClearKeys em IModelObject. Ele removerá todas as chaves do repositório de metadados especificado. Esse método não tem efeito em nenhum repositório pai.

Enumeração de objeto no modelo de dados

enumerando objetos no modelo de dados

Há duas interfaces de enumeração de chave principal 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:

Keys – 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 quaisquer acessadores de propriedade subjacentes. Esse estilo de enumeração pode retornar valores IModelPropertyAccessor brutos em caixa em 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 às chaves/valores brutos em um objeto. Essas referências podem ser salvas e usadas posteriormente para obter ou definir a chave subjacente ou o valor bruto.

KeyEnumerator: Enumeração de chaves sintéticas

A interface IKeyEnumerator é a interface única para a enumeração de todas as chaves (por chave, valor ou referência) em um objeto de instância e todos os modelos pai associados em sua cadeia de modelo pai. A interface é definida da seguinte maneira:

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;
}

Redefinir

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.

GetNext

O método GetNext move o enumerador para frente e retorna a chave nessa posição na enumeração.

IRawEnumerator: a enumeração de constructos de linguagem nativa ou subjacente (C/C++)

A interface IRawEnumerator é a única interface para a enumeração de todos os constructos nativos/idiomas (por valor ou referência) dentro de um objeto que representa um constructo nativo dentro do espaço de endereço do destino de depuração. A interface é definida da seguinte maneira:

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

Redefinir

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á o primeiro constructo nativo/idioma enumerado.

GetNext

O método GetNext move o enumerador para frente e retorna o constructo nativo/idioma nessa posição na enumeração.


Consulte também

Este tópico faz parte de uma série que descreve as interfaces acessíveis do C++, como usá-las para criar uma extensão de depurador baseada em C++ e como usar outras construções de modelo de dados (por exemplo: JavaScript ou NatVis) de uma extensão de modelo de dados C++.

Visão geral do modelo de dados do depurador C++

interfaces C++ do modelo de dados do depurador de

objetos C++ do modelo de dados do depurador

conceitos do C++ do modelo de dados do depurador

de script C++ do modelo de dados do depurador