Abfrageschemadefinitionen

  • Artikel

Anwendungen, die mit Dataverse erstellt wurden, müssen in der Lage sein, sich an Änderungen an Schemadefinitionen anzupassen. Neue Tabellen, Spalten, Beziehungen und Beschriftungen können über die Konfiguration oder durch Importieren einer Lösung hinzugefügt oder geändert werden. Da Anwendungen auf diese Änderungen reagieren müssen, sind sie beim Start häufig darauf angewiesen, Schemadefinitionen abzurufen. Die Gesamtmenge an Daten, die das Schema von einer Dataverse-Organisation beschreibt, kann sehr groß sein. Sie müssen in der Lage sein, genau die Daten zu erhalten, die Sie benötigen.

Die RetrieveMetadataChanges-Nachricht bietet zwei Möglichkeiten:

  1. Anfrage: Erstellen Sie eine einzelne Abfrage, um nur die Schemadaten abzurufen, die Sie benötigen. Dieser Artikel konzentriert sich auf das Verfassen von Abfragen.
  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. Zwischenspeichern kann zu einer erheblichen Verbesserung der Startzeit Ihrer Anwendung führen. Cache-Management wird in Cache-Schemadaten behandelt.

Werten Sie andere Optionen aus, um Schemadefinitionen abzurufen

Beim Erstellen einer Abfrage zum Abrufen von Schemadefinitionen bietet die RetrieveMetadataChanges-Nachricht den Vorteil, eine einzelne Anforderung zu definieren, die mehrere Tabellendefinitionen umfassen und Details für abgeleitete Typen zurückgeben und einen Cache im Laufe der Zeit verwalten kann.

Die folgende Tabelle fasst andere Möglichkeiten zum Abrufen von Schemadefinitionen zusammen, aber keine davon bietet Funktionen zum Verwalten eines Caches im Laufe der Zeit.

Nachricht Beschreibung und Einschränkungen
RetrieveAllEntities Ruft Daten für alle Tabellen ab, einschließlich aller Spalten,Rechte und Beziehungen, wenn Sie dies wünschen.
Siehe: RetrieveAllEntitiesRequest- und RetrieveAllEntitiesResponse-Klassen.

Einschränkungen: Sie können zwar den Parameter EntityFilters verwenden, um einige Teile auszuschließen, dies ist jedoch ein sehr kostspieliger Vorgang.
RetrieveEntity Sie können die Definition jeder einzelnen Tabelle abrufen, einschließlich aller Spalten, Berechtigungen und Beziehungen, wenn Sie dies wünschen.
Siehe: Abrufen und Aktualisieren einer Tabelle

Einschränkungen: Sie können zwar den Parameter EntityFilters verwenden, um einige Daten auszuschließen, Sie können jedoch nicht auswählen, welche spezifischen Eigenschaften Sie wünschen, dies ist dennoch ein kostspieliger Vorgang.
RetrieveAttribute Sie können die vollständige Definition jedes einzelnen Attributs abrufen.
Siehe: Abrufen einer Spalte

Einschränkungen: Sie können die gewünschten Eigenschaften nicht auswählen.
RetrieveRelationship Sie können die vollständige Definition jeder einzelnen Beziehung abrufen.
Siehe: Abrufen von Tabellenbeziehungen

Einschränkungen: Sie können die gewünschten Eigenschaften nicht auswählen.
RetrieveAllOptionSets Sie können Informationen zu allen in der Organisation definierten globalen Auswahlmöglichkeiten abrufen.
Siehe: Einfügen, Aktualisieren, Löschen und Sortieren globaler Auswahlmöglichkeiten

Einschränkungen: Auswahlmöglichkeiten, die nur lokal innerhalb einer Spalte definiert sind, sind nicht enthalten.
RetrieveEntityKey Sie können die Definition für alle alternativen Schlüssel für eine bestimmte Tabelle abrufen.
Siehe: Abrufen und Löschen von Alternativschlüsseln

Basis-RetrieveMetadataChanges-Beispiel

Ein einfaches Beispiel dafür, was Sie mit RetrieveMetadataChanges machen können. Vergleichen Sie das, mit dem, was Sie mit der Web-API und dem EntityDefinitions-Entitätssatz tun können.

Mit der Web-API können Sie eine Abfrage wie folgt erstellen:

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=LogicalName eq 'account' or LogicalName eq 'contact'&$expand=Attributes($select=LogicalName;$filter=IsValidForCreate eq true)

Diese Abfrage gibt Daten sowohl aus den Firma- als auch aus den Kontakttabellendefinitionen zurück und erweitert alle Spaltendefinitionen, bei denen IsValidForCreate wahr ist.

Die folgenden Beispiele zeigen, wie Sie dieselbe Abfrage mit RetrieveMetadataChanges erstellen.

/// <summary>
/// Get the SchemaName for the account and contact tables together with
/// the LogicalName of any attributes which are valid for create
/// </summary>
/// <param name="service"></param>
static void SimpleRetrieveMetadataChangesExample(IOrganizationService service) {

    var query = new EntityQueryExpression
    {
        Properties = new MetadataPropertiesExpression("SchemaName", "Attributes"),
        Criteria = new MetadataFilterExpression(filterOperator: LogicalOperator.Or)
        {
            Conditions = {
                {
                    new MetadataConditionExpression(
                        propertyName:"LogicalName",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:"account")
                },
                {
                    new MetadataConditionExpression(
                        propertyName:"LogicalName",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:"contact")
                }
            }, 
        },
        AttributeQuery = new AttributeQueryExpression
        {
            Properties = new MetadataPropertiesExpression("LogicalName"),
            Criteria = new MetadataFilterExpression(filterOperator: LogicalOperator.And)
            {
                Conditions = {
                    {
                        new MetadataConditionExpression(
                        propertyName:"IsValidForCreate",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:true)
                    }
                }
            }            
        },
        LabelQuery = new LabelQueryExpression { 
             FilterLanguages = {
                { 1033 }
            } 
        }
        
    };

    var request = new RetrieveMetadataChangesRequest
    {
        Query = query
    };

    var response = (RetrieveMetadataChangesResponse)service.Execute(request);

    response.EntityMetadata.ToList().ForEach(em => {

        Console.WriteLine($"Entity SchemaName:{em.SchemaName}");
        em.Attributes.ToList().ForEach(a => {
            Console.WriteLine($"\tAttribute LogicalName:{a.LogicalName}");
        });
    });
}

Ausgabe:

Entity SchemaName:Account
        Attribute LogicalName:emailaddress3
        Attribute LogicalName:emailaddress1
        Attribute LogicalName:address1_city
    <List truncated for brevity>
Entity SchemaName:Contact
        Attribute LogicalName:contactid
        Attribute LogicalName:emailaddress3
        Attribute LogicalName:emailaddress2
    <List truncated for brevity>

Erstellen Sie Abfrage mit EntityQueryExpression

Verwenden Sie EntityQueryExpression, um die RetrieveMetadataChanges-Query-Eigenschaft festzulegen.

EntityQueryExpression hat die folgenden Eigenschaften:

Eigenschaften Type Beschreibung des Dataflows
Properties MetadataPropertiesExpression Stellen Sie PropertyNames auf eine Liste mit Eigenschaftsnamen ein, die zurückgegeben werden sollen. Oder Sie können AllProperties auf wahr festlegen, um alle Eigenschaften zurückzugeben. Bei Artikeln, die über diese verfügen, müssen Sie die Eigenschaftennamen MetadataId, LogicalName oder HasChanged nicht hinzufügen. Diese Eigenschaften werden immer berücksichtigt.
Criteria MetadataFilterExpression Siehe Begrenzen Sie die zurückgegebenen Daten mit MetadataFilterExpression
AttributeQuery AttributeQueryExpression Folgt dem gleichen Muster wie EntityQueryExpression. AttributeQueryExpression hat auch Properties und Criteria, um zu steuern, welche Spaltendefinitionen zurückgegeben werden sollen.

Hinweis: Wenn Sie AttributeQuery verwenden, muss Attributes eine der Properties sein, die für die EntityQueryExpression angefordert werden.
RelationshipQuery RelationshipQueryExpression Folgt dem gleichen Muster wie EntityQueryExpression. RelationshipQueryExpression hat auch Properties und Criteria, um zu steuern, welche Beziehungsdefinitionen zurückgegeben werden sollen.

Hinweis: Wenn Sie RelationshipQuery, OneToManyRelationships, ManyToOneRelationships oder ManyToManyRelationships verwenden, müssen sie eine der Properties sein, die für die EntityQueryExpression angefordert werden.
KeyQuery EntityKeyQueryExpression Folgt dem gleichen Muster wie EntityQueryExpression. EntityKeyQueryExpression hat auch Properties und Criteria, um zu steuern, welche Alternativschlüsseldefinitionen zurückgegeben werden sollen.

Hinweis: Wenn Sie KeyQuery verwenden, muss Keys eine der Properties sein, die für die EntityQueryExpression angefordert werden.
LabelQuery LabelQueryExpression Verwenden Sie die FilterLanguages-Eigenschaft, um die zurückgegebenen Sprachen einzuschränken. Wenn in einer Organisation viele Sprachen bereitgestellt werden, erhalten Sie Beschriftungen für alle Sprachen, die die zurückgegebenen Daten erheblich erweitern könnten. Wenn Ihre App für einen einzelnen Benutzer bestimmt ist, sollten Sie den bevorzugten LCID-Sprachcode des Benutzers angeben. Siehe Rufen Sie den bevorzugten Sprachcode des Benutzers ab

Hinweis

Der Query-Parameter ist optional. Sie können also RetrieveMetadataChanges ohne Filter verwenden, aber dies entspricht der Verwendung von RetrieveAllEntities. Eine sehr teure Operation.

Begrenzen Sie die zurückgegebenen Daten mit MetadataFilterExpression

Verwenden Sie MetadataFilterExpression für die Criteria Eigenschaften für EntityQueryExpression, AttributeQueryExpression, RelationshipQueryExpression und EntityKeyQueryExpression.

MetadataFilterExpression hat die folgenden Eigenschaften:

Eigenschaften Type Beschreibung des Dataflows
FilterOperator LogicalOperator Steuert, wie Conditions ausgewertet werden. Entweder And oder Or.
Conditions DataCollection<MetadataConditionExpression> Eine Sammlung von auszuwertenden Bedingungen.. Siehe Legen Sie Bedingungen mit MetadataConditionExpression fest
Filters DataCollection<MetadataFilterExpression> Weitere anzuwendende Filter für eine komplexere Abfrage.

Legen Sie Bedingungen mit MetadataConditionExpression fest

Verwenden Sie MetadataConditionExpression für die MetadataFilterExpression Conditions-Eigenschaften.

MetadataConditionExpression hat die folgenden Eigenschaften:

Eigenschaften Type Beschreibung des Dataflows
ConditionOperator MetadataConditionOperator Beschreibt den Vergleichstyp, der auf die Value-Eigenschaft angewendet werden soll.
PropertyName string Der Name der zu auszuwertenden Eigenschaft
Value object Der zu vergleichende Wert (oder die Werte)

Im Allgemeinen können Sie nur Eigenschaften verwenden, die einfache Datentypen, Aufzählungen, BooleanManagedProperty oder AttributeRequiredLevelManagedProperty in einem MetadataFilterExpression darstellen. Sie können keine Bedingungen für Eigenschaften festlegen, bei denen es sich um Sammlungen oder Beschriftungen handelt. Wenn eine BooleanManagedProperty oder AttributeRequiredLevelManagedProperty angegeben ist, kann nur die Eigenschaft Value ausgewertet werden. Filterung für AttributeMetadata.SourceType-Eigenschaft wird nicht unterstützt.

MetadataConditionOperator-Aufzählungswerte

Die MetadataConditionOperator-Aufzählung hat die folgenden Mitglieder:

Feld Beschreibung
Equals Die Werte werden auf Gleichheit verglichen.
NotEquals Die beiden Werte sind nicht gleich.
In Der Wert ist ein einer Werteliste vorhanden.
NotIn Der angegebene Wert stimmt nicht mit einem Wert in einer Liste überein.
GreaterThan Der Wert ist größer als der Vergleichswert.
LessThan Der Wert ist kleiner als der Vergleichswert.

Zurückgegebene Prozessdaten

RetrieveMetadataChangesResponse hat folgende Eigenschaften:

Eigenschaften Type Beschreibung des Dataflows
EntityMetadata EntityMetadataCollection Die angeforderte Tabellendefinition. Wenn Sie Daten abfragen oder einen Cache initialisieren, kann dieser Wert genauso behandelt werden wie die Antwort aus der RetrieveAllEntities-Nachricht. Wenn Sie auf eine bestimmte Spalten-, Beziehungs- oder Alternativschlüsseldefinition zugreifen möchten, müssen Sie die Tabellendefinition zurückgeben, die diese enthält.
ServerVersionStamp string Ein Zeitstempelbezeichner für die abgerufenen Metadaten. Wenn Sie einen Cache mit Schemadefinitionen verwalten, verwenden Sie diesen Wert als ClientVersionStamp-Eigenschaft in nachfolgenden Anforderungen, sodass nur die Änderungen seit der vorherigen Anforderung zurückgegeben werden.
DeletedMetadata DeletedMetadataCollection Daten für die seit der letzten Anfrage gelöschten Elemente. Dieser Wert enthält nur Daten, wenn RetrieveMetadataChanges mit den Parametern ClientVersionStamp und DeletedMetadataFilters gesendet wird. Weitere Informationen finden Sie unter Cache-Schemadaten

Rufen Sie den bevorzugten Sprachcode des Benutzers ab

Die folgenden Beispiele zeigen, wie Sie den bevorzugten LCID-Sprachcode des Benutzers abrufen können.

Sie können die bevorzugte Sprache des Benutzers aus der UserSettings.UILanguageId-Spalte abrufen.

static int? RetrieveUserUILanguageCode(IOrganizationService service)
{
   // To get the current user's systemuserid
   var whoIAm = (WhoAmIResponse)service.Execute(new WhoAmIRequest());

   var query = new QueryExpression("usersettings")
   {
         ColumnSet = new ColumnSet("uilanguageid", "systemuserid"),
         Criteria = new FilterExpression
         {
            Conditions = {
                  {
                     new ConditionExpression(
                        attributeName:"systemuserid",
                        conditionOperator:ConditionOperator.Equal,
                        value: whoIAm.UserId)
                  }
            }
         },
         TopCount = 1
   };

   EntityCollection userSettings = service.RetrieveMultiple(query: query);
   if (userSettings.Entities.Count > 0)
   {
         return (int)userSettings.Entities[0]["uilanguageid"];
   }
   return null;
}

Siehe auch

Cache-Schemadaten
Beispiel für das Abfragen von Schemadefinitionen der Web-API und das Erkennen von Änderungen (C#)
Beispiel für das Abfragen von Schemadefinitionen des SDK für .NET und das Erkennen von Änderungen (C#)
SDK für .NET: Tabellendefinitionen in Microsoft Dataverse
Abfragen von Tabellendefinitionen mithilfe der Web-API

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