Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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 principais noções 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 repositório inteiro de metadados associados 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 ao seu valor que podem afetar a apresentação ou outros atributos associados da chave e do 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, simplificado a partir deste ponto de vista. 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 modelo:
- Um armazenamento de chaves só pode ter um único repositório pai -- não pode ter uma cadeia arbitrária de modelos pai.
- Uma loja de chaves não tem conceitos. Só pode ter o dicionário de tuplas de chave/valor/metadados. Isso significa que as chaves presentes em um armazenamento de chaves são estáticas. Eles não podem ser criados sob demanda por um sistema de linguagem dinâmica.
- Apenas por convenção, os valores em um armazenamento de chaves definido por metadados são restritos a valores básicos (intrínsecos e acessadores de propriedade)
Embora um armazenamento de chaves possa ter um número arbitrário (e 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 que radix um valor ordinal deve ser exibido |
| PreferredFormat | Inteiro: conforme definido pela enumeração PreferredFormat | Indica o tipo de formatação preferido 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 | Booleano | Indica se o host de depuração deve executar a análise de tipo derivado no valor antes de usar (por exemplo: exibir) |
| Ajuda | fio | Texto de ajuda de estilo de dica de ferramenta para a chave que pode ser apresentado pela interface do usuário de uma maneira apropriadamente útil. |
| ActionName | fio | Indica que o método dado (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 | Booleano | Válido somente se a chave ActionName for especificada, indica que essa é a ação padrão para o objeto. |
| AçãoDescrição | fio | Válido somente se a chave ActionName for especificada, isso fornece uma descrição de estilo de dica de ferramenta para a ação. Esse texto pode ser apresentado pela interface do utilizador de uma forma apropriadamente ú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 tal. A maioria dos chamadores especificará null para quaisquer parâmetros de metadados em métodos na interface IKeyStore.
A interface de metadados principais: IKeyStore
A interface IKeyStore é definida da seguinte forma:
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 GetKey método é análogo ao GetKey método em IModelObject. Ele retornará o valor da chave especificada se ela existir no armazenamento de chaves ou no armazenamento pai do armazenamento 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 encaixotado em um IModelObject será retornado. É típico que um cliente chame GetKeyValue por esse motivo.
O método SetKey é análogo ao método SetKey em IModelObject. É o único método que é capaz de criar uma chave e associar metadados a ela dentro do armazenamento de chaves.
O GetKeyValue método é o primeiro método que um cliente irá para encontrar o valor de uma chave específica dentro do repositório de metadados. Se a chave especificada pelo argumento chave existir dentro do repositório (ou no repositório pai), o valor dessa chave e quaisquer metadados associados a ela serão retornados. Se o valor da chave for um acessador de propriedade (um IModelPropertyAccessor encaixotado em um IModelObject), o método GetValue do acessador de propriedade será automaticamente chamado 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 nova chave dentro do repositório de metadados. Se houver uma chave existente, conforme indicado pelo argumento chave, seu valor será definido conforme 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 depois de criados. O uso desse método em um armazenamento de chaves de metadados deve ser pouco frequente.
O método ClearKeys é análogo ao método ClearKeys em IModelObject. Ele removerá todas as chaves do armazenamento de metadados fornecido. Esse método não tem efeito em nenhum armazenamento pai.
enumeração de objeto no modelo de dados
enumerando objetos no modelo de dados
Há duas interfaces de enumeração de chave principais 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 IModelPropertyAccessor brutos encaixotados 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 automaticamente resolvidos 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 posteriormente usadas 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) dentro de um objeto de instância e todos os modelos pai associados em sua cadeia de modelos pai. A interface é definida da seguinte forma:
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 move o enumerador para frente 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 é a interface ú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 da seguinte forma:
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/language enumerada.
O método GetNext move o enumerador para frente e retorna a construção native/language nessa posição na enumeração.
Ver 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 Depurador Data Model C++
Depurador Data Model C++ Interfaces
Depurador Data Model C++ Objects