Daten mithilfe des SDK für .NET abfragen

Das SDK für .NET bietet mehrere Methoden zum Abfragen von Daten. Jede hat verschiedene Vorteile.

Anfragen senden

FetchExpression, QueryExpression, znd QueryByAttribute stammen von QueryBase abstrakten Klassen. Es gibt zwei Möglichkeiten, um Ergebnisse einer Abfrage anzuzeigen, die mit dieser Klassen definiert wird:

• Sie können eine Instanz einer dieser Klassen als query-Parameter für die IOrganizationService.RetrieveMultiple-Methode weitergeben.

• Sie können die RetrieveMultipleRequest.Query-Eigenschaft der Klasse festlegen und die IOrganizationService.Execute-Methode verwenden.

  Grundsätzlich wird die Methode IOrganizationService.RetrieveMultiple verwendet. Sie können jedoch auch die RetrieveMultipleRequest-Klasse verwenden, um optionale Parameter zu verwenden oder die Anforderung als Teil eines Batches mit den ExecuteMultipleRequest- oder ExecuteTransactionRequest-Klassen zu senden.

Beide Methoden geben eine EntityCollection zurück, welch die Ergebnisse der Abfrage in der Entities Sammlungseigenschaft enthält. EntityCollection verfügt über weitere Eigenschaften zum Verwalten der zurückgegebenen Paging-Ergebnisse.

Wenn Sie Daten mithilfe dieser Klassen abrufen, müssen Sie einige Konzepte verstehen. Im weiteren Verlauf dieses Artikels werden allgemeine Konzepte beim Abrufen von Daten mithilfe des SDK für .NET-Klassen erläutert.

Spalten mit Nullwerten werden nicht zurückgegeben

Wenn eine Tabellenspalte einen Nullwert enthält oder wenn die Spalte nicht angefordert war, bezieht die Entity.Attributes-Sammlung den Wert nicht mit ein. Es gibt keinen Schlüssel, um darauf zuzugreifen oder zurückzugeben. Das Fehlen des Attributs gibt an, dass es Null ist.

Spalten, die nicht zum Lesen gültig sind, geben immer Nullwerte zurück. In der Definition dieser Spalten ist die AttributeMetadata.IsValidForRead-Eigenschaft auf false gesetzt.

Früh gebundene Klassen verwalten Nullwerte

Wenn Sie den Stil der frühe Bindung verwenden, verwalten die Eigenschaften der generierten Klassen, die von der Entitätsklasse erben, dies und gehen einen Nullwert zurück. Erfahren Sie mehr über das Generieren von früh gebundenen Klassen

Nullwerte durch die Verwendung spät gebundener Klassen verringern

Wenn Sie den Stil der späten Bindung verwenden und versuchen, mit einem Indexer in den Entity.Attributes- oder Entity.FormattedValues-Sammlungen auf den Wert zuzugreifen, wird eine KeyNotFoundException mit der Nachricht The given key was not present in the dictionary angezeigt.

Um dieses Problem zu vermeiden, wenn Sie die späte Bindung nutzen, können Sie zwei Strategien verwenden:

1. Verwenden Sie für eine Spalte, die null sein könnte, die Entity.Contains(System.String)-Methode, um zu überprüfen, ob der Spaltenwert null ist, bevor Sie versuchen, mit einem Indexer darauf zuzugreifen. Zum Beispiel:

   Money revenue = (entity.Contains("revenue")? entity["revenue"] : null);

2. Verwenden Sie die Entity.GetAttributeValue<T>(System.String)-Methode, um auf den Wert zuzugreifen. Zum Beispiel:

   Money revenue = entity.GetAttributeValue<Money>("revenue");

   Hinweis

   Wenn der mit Entity.GetAttributeValue<T>(System.String) angegebene Typ ein Werttyp ist, der nicht Null sein darf, z. B. Boolean oder DateTime , ist der zurückgegebene Wert der Standardwert, z. B. false oder 1/1/0001 12:00:00 AM anstatt Null.

Jede Anfrage kann bis zu 5.000 Datensätze zurückgeben

Interaktive Anwendungen beschränken typischerweise die Anzahl der angezeigten Datensätze auf eine Zahl, mit der Menschen interagieren können, und bieten dann die Möglichkeit, durch die Datenseiten zu navigieren. Beispielsweise sind modellbasierte Apps auf eine persönliche Option angewiesen, die es den Benutzenden ermöglicht, einen Wert zwischen 25 und 250 auszuwählen. Diese Information wird in der Spalte UserSettings.PagingLimit gespeichert.

Anwendungen, die Daten aus Dataverse abrufen, ohne Daten in einer App anzuzeigen, müssen keine Seitengröße angeben. Die standardmäßige und maximale Seitengröße beträgt 5.000 Zeilen. Wenn Sie keine Seitengröße festlegen, gibt Dataverse bis zu 5.000 Datenzeilen gleichzeitig zurück. Um mehr Zeilen zu erhalten, müssen Sie zusätzliche Anfragen senden.

Die Paging-Funktion funktioniert am besten, wenn Sie die Paging-Cookie-Daten verwenden, die Dataverse mit der EntityCollection.PagingCookie-Eigenschaft zurückgibt. Dies ist jedoch nicht erforderlich und einige Anforderungen geben keinen Paging-Cookie-Wert zurück. Erfahren Sie mehr:

• Ergebnisse mithilfe von FetchXml auslagern
• Paging von Ergebnissen mit QueryExpression

Für einige Spalten werden formatierte Werte zurückgegeben

Greifen Sie für jede Entität in der EntityCollection.Entities mithilfe der Entity.Attributes-Sammlung auf die Datenwerte der Tabellenspalte (Attribute) zu.

Sie können einfache Datentypen wie Zahlen und Zeichenfolgen direkt in Anwendungen anzeigen und bearbeiten. Für bestimmte Datentypen stellt Dataverse schreibgeschützte, formatierte Zeichenfolgenwerte bereit, die Sie in Anwendungen anzeigen können. Das Format einiger dieser Zeichenfolgenwerte hängt von Einstellungen ab, welche die Administrierenden festlegen und die alle Benutzenden überschreiben können.

• Administrierende können standardmäßige regionale Optionen anpassen, die für alle neuen Benutzenden gelten. Diese Einstellungen werden in der Organisationstabelle gespeichert.
• Benutzende können diese Einstellungen mit ihren persönlichen Präferenzen überschreiben. Diese Einstellungen werden in der UserSettings-Tabelle gespeichert.

Verwenden Sie die Sammlung Entity.FormattedValues, um auf formatierte Werte für diese Spaltentypen zuzugreifen:

Im folgenden Beispiel wird gezeigt, wie Sie auf die formatierten Zeichenfolgenwerte für die folgenden Kontospalten zugreifen:

static void FormattedValuesExample(IOrganizationService service)
{
    List<string> columns = new() {
        "name",
        "primarycontactid",
        "createdon",
        "revenue",
        "statecode"
    };

    QueryExpression query = new("account")
    {
        ColumnSet = new ColumnSet(columns.ToArray()),
        TopCount = 3
    };

    EntityCollection accounts = service.RetrieveMultiple(query);

    accounts.Entities.ToList().ForEach(x =>
    {
        string name = (string)x.Attributes["name"];
        string primarycontactid = x.Contains("primarycontactid") ? 
           x.FormattedValues["primarycontactid"] : 
           string.Empty;
        string createdon = x.FormattedValues["createdon"];
        string revenue = x.Contains("revenue") ? 
           x.FormattedValues["revenue"] : 
           string.Empty;
        string statecode = x.FormattedValues["statecode"];

        Console.WriteLine(@$"
name:{name}
    primary contact: {primarycontactid}
    created on: {createdon}
    revenue: {revenue}
    status: {statecode}"
            );
    });
}

Die formattierten Ergebnisse werden wie folgt angezeigt:

name:A Datum (sample)
  primary contact: Rene Valdes (sample)
  created on: 2/28/2020 11:04 AM
  revenue: $10,000.000
  status: Active

name:City Power & Light (sample)
  primary contact: Scott Konersmann (sample)
  created on: 2/28/2024 11:04 AM
  revenue: $100,000.000
  status: Active

name:Contoso Pharmaceuticals (sample)
  primary contact: Robert Lyon (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $60,000.000
  status: Active

Spalten, die einen Alias verwenden, geben einen AliasedValue zurück

Wenn Sie aggregierte Werte abrufen, müssen Sie einen Namen für die Spalte angeben, die den aggregierten Wert enthält. Sie können für „normale“ Abfragen auch andere Spaltennamen angeben, dies ist jedoch weniger üblich.

Wenn Sie einen Alias angeben, wird der zurückgegebene Wert in einen Aliaswert verpackt. Der AliasedValue-Klasse hat drei Eigenschaften:

Wenn Sie ein Spaltenalias verwenden, müssen Sie die Value--Eigenschaft umwandeln, um auf den zurückgegebenen Wert zuzugreifen.

Weitere Informationen zu Spaltenaliasen:

• FetchXMl-Spaltenaliase
• QueryExpression-Spaltenaliase

Konvertieren von Abfragen zwischen FetchXML und QueryExpression

Sie können QueryExpression-Abfragen in FetchXml und FetchXml-Abfragen in QueryExpression konvertieren, indem Sie die Klassen QueryExpressionToFetchXmlRequest und FetchXmlToQueryExpressionRequest verwenden.

Die Tabelle SavedQuery speichert Systemansichten für eine Tabelle (Entitätstyp) und die Tabelle UserQuery speichert gespeicherte Benutzerabfragen. Andere Tabellen können eine Abfrage auch als FetchXml-Zeichenfolge speichern. Diese Methoden ermöglichen das Konvertieren einer FetchXml-Zeichenfolge in QueryExpression, sodass sie mit dem Objektmodell bearbeitet und dann wieder in FetchXml konvertiert werden und somit als Zeichenfolge gespeichert werden kann.

Weitere Informationen: Beispiel: Konvertieren von Abfragen zwischen Fetch und QueryExpression

Grenzwerte für Abfragebedingungen

Dataverse hat einen Grenzwert von insgesamt 500 zulässigen Bedingungen in einer Abfrage. Alle Joins, die in der Abfrage enthalten sind, werden zu diesem Grenzwert hinzugezählt. Wenn eine Abfrage (und ihre Verknüpfungen) 500 Bedingungen überschreitet, erhalten Benutzende beim Ausführen der Abfrage die folgende Fehlermeldung: Number of conditions in query exceeded maximum limit..

In diesem Fall muss ein Benutzer entweder:

• Reduzieren Sie die Anzahl der Bedingungen in der Abfrage.
• Verwenden Sie die In-Klausel, die GUIDs und Zeichenfolgen mit bis zu 850 Zeichen ohne einen Grenzwert für Ganzzahlen zulässt.

Bei allen Filterbedingungen für Zeichenfolgenwerte muss auf die Groß- und Kleinschreibung geachtet werden

Beim Vergleichen von Zeichenfolgenwerten müssen Sie nicht auf die Groß- und Kleinschreibung achten. Die folgende QueryExpression-Abfrage gibt Kontodatensätze mit dem Namen Contoso, Ltd und CONTOSO, LTD zurück.

QueryExpression query = new("account")
{
   ColumnSet = new ColumnSet("name"),
   Criteria = new FilterExpression(LogicalOperator.And) { 
      Conditions = {
         { 
               new ConditionExpression(
                  attributeName: "name", 
                  conditionOperator: ConditionOperator.Equal, 
                  value: "CONTOSO, LTD") 
         }
      }
   },
   TopCount = 3
};