Freigeben über

Cache-Schemadaten

  • Artikel

Einige Anwendungen profitieren von der Verwaltung eines dauerhaften Caches von Schemadefinitionen für eine Dataverse-Organisation. Zum Beispiel:

  • Anwendungen, die funktionieren müssen, während keine Verbindung zum Dataverse-Server besteht
  • Anwendungen, die empfindlich auf begrenzte Netzwerkbandbreite reagieren, z. B. mobile Anwendungen

Dataverse hat viele Schemadefinitionsdaten, und nur wenige Anwendungen müssen sie alle nachverfolgen. Es ist wichtig, die Datenmenge zu begrenzen, die zwischengespeichert werden soll.

Die RetrieveMetadataChanges-Nachricht bietet zwei Möglichkeiten:

  1. Anfrage: Erstellen Sie eine einzelne Abfrage, um nur die Schemadaten abzurufen, die Sie benötigen. Das Erstellen von Abfragen wird in den Abfrageschemadefinitionen behandelt.
  2. Cache-Verwaltung: Wenn Sie die Schemadefinitionsdaten mit Ihrer App zwischenspeichern, können Sie mit RetrieveMetadataChanges effizient nur die Änderungen seit Ihrer letzten Abfrage abrufen. Verwenden Sie die Informationen zu diesen Änderungen, um Elemente in Ihrem Cache hinzuzufügen oder zu entfernen. Das Zwischenspeichern von Schemadaten kann die Startzeit Ihrer Anwendung erheblich verkürzen und steht im Mittelpunkt dieses Artikels.

Nachdem Sie eine Abfrage für die Schemadaten definiert haben, die Sie zwischenspeichern möchten, können Sie andere Funktionen der RetrieveMetadataChanges-Nachricht zum Erstellen und Verwalten eines Cache von Dataverse-Schemadaten verwenden.

Einen Cache erstellen

Wie in Abfrageschemadefinitionen beschrieben besteht der erste Schritt darin, eine Abfrage zu erstellen, die die Art der Schemainformationen definiert, an denen Sie interessiert sind. Dann nutzen Sie die RetrieveMetadataChanges-Nachricht, um diese Abfrage auszuführen und die in Ihrer Anwendung zurückgegebenen Schemadefinitionen zwischenzuspeichern. Sie sollten eine Möglichkeit finden, diese Daten beizubehalten, die für die Anforderungen Ihrer App geeignet ist. Sie können sie als Datei speichern, die Ihre Anwendung beim Start liest. Sie müssen auch Daten über den letzten Ausführungszeitpunkt der Abfrage speichern. Strukturieren Sie Ihren Cache so, wie es für Ihre Anwendung sinnvoll ist. Um das Entfernen gelöschter Elemente zu verwalten, ist es wichtig, dass Ihr Cache die MetadataId als eindeutige Kennung verwendet. Weitere Informationen: Entfernen gelöschter Elemente.

Änderungen erkennen

Es ist kein Ereignis verfügbar, um zu ermitteln, wann Schemadefinitionsänderungen auftreten. Die Anforderungen Ihrer Anwendung sollten die Aktualisierung des Caches erfordern. Normalerweise rufen Personen Änderungen ab, wenn die Anwendung gestartet wird. Sie können das System jedoch regelmäßig abfragen, wenn Sie Änderungen im Laufe der Zeit erkennen möchten. Unabhängig von Ihrer Strategie ist es wichtig, den Zeitpunkt der vorherigen Anfrage im Auge zu behalten.

Die RetrieveMetadataChangesResponse.ServerVersionStamp-Eigenschaft enthält Informationen über den Zeitpunkt, an dem die Anfrage an RetrieveMetadataChanges aufgetreten ist. Sie müssen den ServerVersionStamp-Wert aus der vorherigen Antwort nehmen und ihn als Wert für RetrieveMetadataChangesRequest.ClientVersionStamp verwenden, wenn Sie das Element erneut mit derselben Abfrage senden.

Wenn Sie die ClientVersionStamp-Eigenschaft in der Anfrage einschließen, enthält die zurückgegebene Eigenschaft RetrieveMetadataChangesResponse.EntityMetadata nur die seit der letzten Anforderung geänderten oder hinzugefügten Schemadaten. Sie können sie Ihrem Cache hinzufügen.

Wenn Sie auch den DeletedMetadataFilters-Parameter einschließen, werden alle Schemaelemente, die seit der letzten Anforderung gelöscht wurden, in der Eigenschaft RetrieveMetadataChangesResponse.DeletedMetadata eingeschlossen. Sie können sie aus Ihrem Cache entfernen.

Dieses Ergebnis sollte kleiner und schneller sein, als wenn die ursprüngliche Abfrage erneut ausgeführt würde.

Abgelaufenen Cache verwalten

Informationen über Änderungen werden standardmäßig 90 Tage gespeichert. Dieser Wert wird in der Organization.ExpireSubscriptionsInDays-Eigenschaft gespeichert. Wenn Sie eine Anforderung mit einem ClientVersionStamp-Wert senden, der älter ist als der Einstellungswert, gibt Dataverse einen ExpiredVersionStamp-Fehler (0x80044352) zurück. Sie sollten darauf vorbereitet sein, diesen speziellen Fehler zu beheben und Ihren Cache neu zu initialisieren, wenn er auftritt.

Hinweis

Sie sollten darauf vorbereitet sein, diesen Fehler zu bewältigen, auch wenn Sie glauben, dass Ihr Wert immer weniger als 90 Tage betragen wird. Dieser Fehler wird ausgegeben, wenn sich Änderungen auf dem Server auf die genaue Nachverfolgung gelöschter Schemadaten auswirken. Zum Beispiel macht das Ändern der Organization.ExpireSubscriptionsInDays-Eigenschaft alle vorherigen VersionStamp-Werte ungültig. Einige dieser Änderungen werden möglicherweise nicht durch von Ihnen vorgenommene Aktionen verursacht, sondern können durch Systemwartungen ausgelöst werden.

Geänderte Elemente hinzufügen

Genau wie beim ersten Abfragen zum Initialisieren des Caches umfasst die Eigenschaft RetrieveMetadataChangesResponse.EntityMetadata, die für nachfolgende Anforderungen mithilfe von RetrieveMetadataChangesRequest.ClientVersionStamp zurückgegeben wird, die vollständige Hierarchie der geänderten Elemente.

Jedes Element in der Hierarchie hat einen nullbaren booleschen HasChanged-Wert. Wenn dieser Wert falsch ist, bedeutet dies, dass sich das aktuelle Element nicht geändert hat, sich aber etwas darunter in der Hierarchie geändert hat. Wenn der HasChanged-Wert wahr ist, bedeutet dies, dass sich das aktuelle Element in der Hierarchie geändert hat.

Hinweis

Wenn Sie EntityMetadata.Privileges in Ihrer Abfrage anfordern, werden die Rechte immer zurückgegeben, unabhängig davon, ob sie sich geändert haben oder nicht. Rechte ändern sich normalerweise nicht.

Nachverfolgungsoption

Ein Bereich, der möglicherweise nicht intuitiv erscheint, ist die Art und Weise, wie Optionen für Auswahlspalten nachverfolgt werden. Dieser Bereich ist ein gutes Beispiel zum Verständnis der HasChanged-Eigenschaft.

Wenn einer Auswahlspalte eine neue Option hinzugefügt wird, werden die folgenden Daten in der Hierarchie mit der RetrieveMetadataChangesResponse.EntityMetadata-Eigenschaft zurückgegeben:

Sie wissen, dass EntityMetadata und EnumAttributeMetadata sich nicht geändert haben, denn die HasChanged-Eigenschaft ist falsch. Nur die OptionSetMetadata.HasChanged-Eigenschaft ist wahr. Es werden alle aktuell gültigen Optionen zurückgegeben. Die OptionMetadata.HasChanged-Eigenschaft für alle Optionen, einschließlich der neuen, ist NULL.

Nur die neu erstellte Option enthält Daten für die Label-Eigenschaft. Die OptionMetadata.HasChanged-Eigenschaft ist nur dann wahr, wenn sich eine ihrer Eigenschaften (wie Color oder Label) ändert.

Gelöschte Elemente entfernen

Wenn Sie sowohl den Parameter ClientVersionStamp als auch den Parameter DeletedMetadataFilters für eine RetrieveMetadataChanges-Nachricht einschließen, enthält die RetrieveMetadataChangesResponse.DeletedMetadata-Eigenschaft Daten zu allen gelöschten Elementen. Bei dieser Eigenschaft handelt es sich um ein DeletedMetadataCollection-Element das eine Reihe von Keys und Values enthält. Die Schlüssel sind DeletedMetadataFilters-Enumerationswerte und Sie können diese Werte verwenden, um auf eine Teilmenge der gelöschten Werte zuzugreifen.

Hinweis

Der DeletedMetadataFilters-Parameter ist optional, und wenn Sie ihn einbeziehen, wirkt sich dies etwas auf die Leistung aus, da die Daten direkt aus der Datenbank und nicht aus dem internen Cache abgerufen werden. Verwenden Sie ihn nur, wenn Sie gelöschte Elemente erkennen müssen, und setzen Sie den Filterwert auf die Mindestmenge der Daten, die zurückgegeben werden müssen.

Die gelöschten Werte werden als Sammlung von Guid-Werten zurückgegeben. Die Werte für gelöschte Elemente werden nicht basierend auf Ihrer Abfrage gefiltert. Es gibt viele Guid-Werte, die sich nicht in Ihrem Cache befinden, aber die Guid-Werte für Ihr zwischengespeichertes Element sind enthalten. Sie müssen nach übereinstimmenden Guid-Werten suchen und diese Elemente entfernen. Ignorieren Sie alle Werte, die sich nicht in Ihrem Cache befinden.

Hinweis

Die Definition der Web-API DeletedMetadataFilters EnumType unterscheidet sich geringfügig der SDK-DeletedMetadataFilters-Aufzählung.

Die Web-API DeletedMetadataFilters EnumType hat kein Entity-Mitglied. Sie müssen stattdessen Default verwenden.

Nachverfolgung gelöschter Optionen

Beachten Sie, dass die DeletedMetadataFilters-Aufzählung ein Mitglied für OptionSet aber keine Option enthält. Wenn Optionen aus einer Auswahlspalte entfernt werden, finden Sie keinen Verweis auf eine bestimmte Option, die gelöscht wurde. Sie müssen zu Ihren zwischengespeicherten Optionen gehen und sie mit den aktuellen Optionen vergleichen, die für dieses OptionSet zurückgegeben werden.

Siehe auch

Beispiel für das Abfragen von Schemadefinitionen der Web-API und das Erkennen von Änderungen (C#)
Beispiel für das Abfragen von SDK for .NET-Abfrageschemas und das Erkennen von Änderungen (C#)
Abfrageschemadefinitionen

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).