Partilhar via

Dados do esquema de cache

Alguns aplicativos se beneficiam da manutenção de um cache persistente de definições de esquema para uma organização do Dataverse. Por exemplo:

  • Aplicativos que precisam funcionar enquanto desconectados do servidor do Dataverse.
  • Aplicativos sensíveis à largura de banda de rede limitada, como aplicativos móveis.

O Dataverse tem muitos dados de definição de esquema e poucos aplicativos devem acompanhar tudo isso. Limitar a quantidade de dados ao cache é essencial.

A RetrieveMetadataChanges mensagem fornece dois recursos:

  1. Consulta: Redigir uma única consulta para recuperar apenas os dados de esquema necessários. A composição de consultas é abordada em Definições de Esquema de Consulta.
  2. Gerenciamento de cache: se você armazenar em cache os dados de definição de esquema com seu aplicativo, poderá usar RetrieveMetadataChanges para recuperar com eficiência apenas as alterações desde sua última consulta. Use as informações sobre essas alterações para adicionar ou remover itens em seu cache. Fazer cache dos dados de esquema pode resultar em uma melhoria significativa no tempo de inicialização do seu aplicativo e é o foco deste artigo.

Depois de definir uma consulta para os dados de esquema que deseja armazenar em cache, use outros recursos da RetrieveMetadataChanges mensagem para criar e manter um cache de dados de esquema do Dataverse.

Criar um cache

Conforme descrito em Definições de Esquema de Consulta, a primeira etapa é criar uma consulta que defina o tipo de informações de esquema em que você está interessado. Em seguida, use a RetrieveMetadataChanges mensagem para executar essa consulta e armazenar em cache as definições de esquema retornadas em seu aplicativo. Encontre uma maneira de persistir esses dados apropriados para as necessidades do seu aplicativo. Você pode salvá-lo como um arquivo que seu aplicativo lê quando ele é iniciado. Você também precisa salvar dados sobre a última vez que executou a consulta. Estruturar seu cache de uma maneira que faça sentido para seu aplicativo. Para gerenciar a remoção de itens excluídos, é importante que o cache use MetadataId como identificador exclusivo. Para obter mais informações, consulte Remover itens excluídos.

Detectar alterações

Nenhum evento existe para detectar quando ocorrem alterações na definição de esquema. Atualize o cache com base nas necessidades do aplicativo. Normalmente, você recupera as alterações quando o aplicativo é iniciado. Mas você pode sondar o sistema regularmente se quiser detectar alterações ao longo do tempo. Independentemente de sua estratégia, acompanhe a hora em que você enviou a solicitação anterior.

A RetrieveMetadataChangesResponse.ServerVersionStamp propriedade contém informações sobre o ponto no tempo em que a solicitação RetrieveMetadataChanges ocorreu. Pegue o valor do ServerVersionStamp da resposta anterior e use-o como o valor para o RetrieveMetadataChangesRequest.ClientVersionStamp quando você enviá-lo novamente usando a mesma consulta.

Quando você inclui a ClientVersionStamp propriedade na solicitação, a RetrieveMetadataChangesResponse.EntityMetadata propriedade retornada contém apenas os dados de esquema alterados ou adicionados desde a solicitação anterior. Você pode adicioná-los ao seu cache.

Se você também incluir o parâmetro, todos os DeletedMetadataFilters itens de esquema excluídos desde a solicitação anterior serão incluídos na RetrieveMetadataChangesResponse.DeletedMetadata propriedade. Você pode removê-los do cache.

Esse resultado é menor e mais rápido do que executar a consulta original novamente.

Gerenciar cache expirado

O Dataverse armazena informações sobre alterações por 90 dias por padrão. Esse valor é armazenado na propriedade Organization.ExpireSubscriptionsInDays . Se você enviar uma solicitação com um ClientVersionStamp valor mais antigo que o valor de configuração, o Dataverse retornará um ExpiredVersionStamp erro (0x80044352). Esteja preparado para lidar com esse erro específico e reinicializar o cache quando ele ocorrer.

Observação

Esteja preparado para gerenciar esse erro mesmo se você achar que seu valor é sempre menor que 90 dias. Esse erro ocorre quando as alterações no servidor afetam o acompanhamento preciso dos dados de esquema excluídos. Por exemplo, alterar a Organization.ExpireSubscriptionsInDays propriedade invalida todos os valores anteriores VersionStamp . Algumas dessas alterações podem não ser causadas por ações que você executa, mas podem ser disparadas pela manutenção do sistema.

Adicionar itens alterados

Assim como quando você executa sua consulta inicial para inicializar o cache, a RetrieveMetadataChangesResponse.EntityMetadata propriedade retornada para solicitações subsequentes usando RetrieveMetadataChangesRequest.ClientVersionStamp inclui a hierarquia completa de itens alterados.

Cada item na hierarquia tem um valor booliano HasChanged anulável. Quando esse valor é falso, significa que o item atual não foi alterado, mas algo abaixo dele na hierarquia foi alterado. Quando o HasChanged valor é verdadeiro, significa que o item atual na hierarquia foi alterado.

Observação

Se você solicitar EntityMetadata.Privileges em sua consulta, os privilégios serão sempre retornados, sejam eles alterados ou não. Privilégios normalmente não mudam.

Opções de acompanhamento

Uma área que pode não parecer intuitiva é como as opções de colunas de escolha são acompanhadas. Essa área é um bom exemplo para entender a propriedade HasChanged.

Quando você adiciona uma nova opção a uma coluna de escolha, os seguintes dados na hierarquia são retornados por meio da RetrieveMetadataChangesResponse.EntityMetadata propriedade:

Você sabe que o EntityMetadata e EnumAttributeMetadata não mudou porque a HasChanged propriedade é falsa. Somente a OptionSetMetadata.HasChanged propriedade é verdadeira. Todas as opções válidas atuais são retornadas. A OptionMetadata.HasChanged propriedade para todas as opções, incluindo a nova, é nula.

Somente a opção recém-criada inclui dados para a Label propriedade. A OptionMetadata.HasChanged propriedade é verdadeira somente quando uma de suas propriedades (como Color ou Label) é alterada.

Remover itens excluídos

Quando você inclui os parâmetros ClientVersionStamp e DeletedMetadataFilters para uma mensagem RetrieveMetadataChanges, a propriedade RetrieveMetadataChangesResponse.DeletedMetadata contém dados sobre quaisquer itens excluídos. Essa propriedade é uma DeletedMetadataCollection que contém um conjunto de Keys e Values. As chaves são DeletedMetadataFilters valores de enumeração e você pode usar esses valores para acessar um subconjunto dos valores excluídos.

Observação

O DeletedMetadataFilters parâmetro é opcional. Incluí-lo pode afetar o desempenho porque o processo recupera dados diretamente do banco de dados e não do cache interno. Use-o somente quando você precisar detectar itens excluídos e definir o valor do filtro como a quantidade mínima de dados que você precisa ter retornado.

Os valores excluídos são retornados como uma coleção de Guid valores. Os valores para itens excluídos não são filtrados com base na consulta. Muitos Guid valores não estão no cache, mas os valores do Guid item armazenado em cache estão incluídos. Você deve procurar os valores correspondentes Guid e remover esses itens. Desconsidere todos os valores que não estão em seu cache.

Observação

A definição da DeletedMetadataFilters EnumType da Web API é ligeiramente diferente da DeletedMetadataFilters Enum do SDK.

A Web API DeletedMetadataFilters EnumType não tem o Entity membro. Use Default em seu lugar.

Acompanhamento de opções excluídas

Observe que a DeletedMetadataFilters enumeração contém um membro para OptionSet, mas não a opção. Se você remover qualquer opção de uma coluna de escolha, não encontrará uma referência a uma opção específica que foi excluída. Você precisa acessar as opções em cache e compará-las com as opções atuais retornadas para o OptionSet.

Consulte também

Definições de esquema de consulta da API Web e detecção de exemplo de alterações (C#)
SDK para .NET, definições de esquema de consulta, e exemplo de detecção de alterações (C#)
Definições de esquema de consulta

  • Last updated on