Almacenar en caché datos de esquema

Algunas aplicaciones se benefician del mantenimiento de una memoria caché persistente de definiciones de esquema para una organización de Dataverse. Por ejemplo:

  • Aplicaciones que necesitan funcionar mientras se está desconectado del servidor de Dataverse
  • Aplicaciones que son sensibles al ancho de banda de red limitado, como aplicaciones móviles

Dataverse tiene una gran cantidad de datos de definición de esquema y pocas aplicaciones deben realizar un seguimiento de todos ellos. Es esencial limitar la cantidad de datos para caché.

El mensaje RetrieveMetadataChanges proporciona dos capacidades:

  1. Consulta: redacte una sola consulta para recuperar solo los datos del esquema que necesita. La redacción de consultas se trata en Definiciones de esquemas de consulta.
  2. Administración de caché : si almacena en caché los datos de definición de esquema con su aplicación, puede usar RetrieveMetadataChanges para recuperar eficientemente solo los cambios desde su última consulta. Utilice la información sobre estos cambios para agregar o quitar elementos en su caché. El almacenamiento en caché de los datos del esquema puede resultar en una mejora significativa en el tiempo de inicio de su aplicación y es el tema central de este artículo.

Después de definir una consulta para los datos del esquema que desea almacenar en caché, puede utilizar otras capacidades del mensaje RetrieveMetadataChanges para crear y mantener un caché de datos de Dataverse del esquema.

Crear una caché

Como se describe en Definiciones de esquema de consulta, el primer paso es crear una consulta que defina el tipo de información del esquema que le interesa. Luego use el mensaje RetrieveMetadataChanges para ejecutar esa consulta y almacenar en caché las definiciones de esquema devueltas en su aplicación. Debe encontrar una manera de conservar estos datos que sea adecuada para las necesidades de su aplicación. Puede guardarlo como un archivo que su aplicación lee cuando se inicia. También debe guardar datos sobre la última vez que ejecutó la consulta. Estructure su caché de manera que tenga sentido para su aplicación. Para gestionar la eliminación de elementos eliminados, es importante que su caché utilice el MetadataId como identificador único. Más información: Quitar elementos eliminados.

Detectar cambios

No hay ningún evento disponible para detectar cuándo se producen cambios en la definición del esquema. Las necesidades de su aplicación deberían impulsar la actualización del caché. La gente suele recuperar los cambios cuando se inicia la aplicación. Pero puede sondear el sistema con regularidad si desea detectar cambios a lo largo del tiempo. Independientemente de su estrategia, es importante realizar un seguimiento de la hora a la que envió la solicitud anterior.

La propiedad RetrieveMetadataChangesResponse.ServerVersionStamp contiene información sobre el punto en el tiempo de la solicitud de RetrieveMetadataChanges. Debes tomar el valor ServerVersionStamp de la respuesta anterior y utilizarlo como el valor para RetrieveMetadataChangesRequest.ClientVersionStamp cuando lo envíe de nuevo usando la misma consulta.

Cuando incluye la propiedad ClientVersionStamp en la solicitud, la propiedad RetrieveMetadataChangesResponse.EntityMetadata devuelta contiene solo los datos de esquema modificados o agregados desde la solicitud anterior. Puedes agregarlos a su caché.

Si también incluye el parámetro DeletedMetadataFilters, cualquier elemento del esquema eliminado desde la solicitud anterior se incluye en la propiedad RetrieveMetadataChangesResponse.DeletedMetadata. Puede eliminarlos de su caché.

Este resultado debería ser más pequeño y más rápido que ejecutar nuevamente la consulta original.

Administrar caché expirada

La información sobre los cambios se almacena durante 90 días de manera predeterminada. Este valor se almacena en la propiedad Organization.ExpireSubscriptionsInDays. Si envía una solicitud con un valor ClientVersionStamp que es anterior al valor de configuración, Dataverse devuelve un error ExpiredVersionStamp (0x80044352). Debe estar preparado para manejar este error específico y reinicializar su caché cuando ocurra.

Nota

Debe estar preparado para manejar este error incluso si piensa que su valor siempre será inferior a 90 días. Este error se generará cuando cualquier cambio en el servidor afecte el seguimiento preciso de los datos de esquema eliminados. Por ejemplo, cambiando la propiedad Organization.ExpireSubscriptionsInDays invalidará todos los valores VersionStamp anteriores. Es posible que algunos de estos cambios no se deban a las acciones que realice, pero podrían desencadenarse por el mantenimiento del sistema.

Agregar elementos cambiados

Al igual que cuando realiza su consulta inicial para inicializar su caché, la propiedad RetrieveMetadataChangesResponse.EntityMetadata devuelta para solicitudes posteriores usando RetrieveMetadataChangesRequest.ClientVersionStamp incluye la jerarquía completa de elementos modificados.

Cada elemento de la jerarquía tiene un valor booleano HasChanged que acepta valores NULL Cuando este valor es falso, significa que el elemento actual no ha cambiado pero algo debajo de él en la jerarquía ha cambiado. Cuando el valor HasChanged es verdadero, significa que el elemento actual de la jerarquía ha cambiado.

Nota

Si solicita EntityMetadata.Privileges en su consulta, siempre se devolverán los privilegios, hayan cambiado o no. Los privilegios normalmente no cambian.

Opciones de seguimiento

Un área que puede no parecer intuitiva es cómo se realiza el seguimiento de las opciones de las columnas de elección. Esta zona es un buen ejemplo para entender la propiedad HasChanged.

Cuando se agrega una nueva opción a una columna de opción, los siguientes datos de la jerarquía se devolverán con la propiedad RetrieveMetadataChangesResponse.EntityMetadata:

Sabe que EntityMetadata y EnumAttributeMetadata no han cambiado porque la propiedad HasChanged es falsa. Solo la propiedad OptionSetMetadata.HasChanged es verdadera. Se devuelven todas las opciones válidas actuales. La propiedad OptionMetadata.HasChanged para todas las opciones, incluida la nueva, es nula.

Solo la opción recién creada incluye datos para la propiedad Label. La propiedad OptionMetadata.HasChanged es verdadera solo cuando una de sus propiedades (como Color o Label) cambia.

Quitar elementos eliminados

Cuando incluye los parámetros ClientVersionStamp y DeletedMetadataFilters para un mensaje RetrieveMetadataChanges , la propiedad RetrieveMetadataChangesResponse.DeletedMetadata contiene datos sobre los elementos eliminados. Esta propiedad es una DeletedMetadataCollection que contiene un conjunto de Keys y Values. Las claves son valores de enumeración DeletedMetadataFilters y puede usar estos valores para acceder a un subconjunto de los valores eliminados.

Nota

El parámetro DeletedMetadataFilters es opcional y hay cierto impacto en el rendimiento cuando lo incluye porque los datos se recuperan directamente de la base de datos en lugar de la memoria caché interna. Úselo solo cuando deba detectar elementos eliminados y establezca el valor del filtro en la cantidad mínima de datos que necesita que se le devuelvan.

Los valores eliminados se devuelven como una colección de valores de Guid. Los valores de los elementos eliminados no se filtran según su consulta. Hay muchos valores Guid que no están en su caché, pero los valores Guid para su elemento almacenado en caché sí están incluidos. Debe buscar cualquier valor de Guid coincidente y eliminar esos elementos. Ignore cualquier valor que no esté en su caché.

Nota

La definición de la API web DeletedMetadataFilters EnumType es ligeramente diferente del SDK Enumeración de DeletedMetadataFilters.

La API web de EnumType de DeletedMetadataFilters no tiene el miembro Entity. Debe usar Default en su lugar.

Seguimiento de opciones eliminadas

Observe que la enumeración DeletedMetadataFilters contiene un miembro para OptionSet, pero no la opción. Si se elimina alguna opción de una columna de opciones, no encontrará una referencia a una opción específica que se eliminó. Debe ir a las opciones almacenadas en caché y compararlas con las opciones actuales devueltas para ese OptionSet.

Consulte también

API web, consultar definiciones de esquema y detectar ejemplo de cambios (C#)
SDK para definiciones de esquema de consulta .NET y detectar ejemplo de cambios (C#)
Consultar definiciones de esquema

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).