Daten mithilfe des SDK für .NET abfragen

Artikel
07/08/2024

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

Methode	Vorteile
FetchExpression-Klasse	Verwenden Sie die geschützte FetchXML-Abfragesprache zum Erstellen komplexer Abfragen, die seitenweise ausgegebene Datensätze oder gruppierte und aggregierte Daten zurückgeben können. Sie können Verknüpfungen erstellen, um Daten aus zugehörigen Datensätzen mitaufzunehmen. FetchXml bietet Funktionen, die andere Optionen nicht bieten. Erfahren Sie, wie man mithilfe von FetchXml Daten abfragt
QueryExpression-Klasse	Verwenden Sie ein stark typisiertes Objektmodell zum Erstellen komplexer Abfragen, die seitenweise ausgegebene Datensätze oder gruppierte und aggregierte Daten zurückgeben können. Sie können Verknüpfungen erstellen, um Daten aus zugehörigen Datensätzen mitaufzunehmen. Unterstützt die meisten Features in FetchXML. Lernen Sie, wie man mit Daten mit QueryExpression abfragt
QueryByAttribute-Klasse	Ein einfacheres Objektmodell für allgemeine Abfragen, um Zeilen zurückzugeben, die allen Kriterien in Ihrer Abfrage entsprechen. Unterstützt Paging, jedoch keine Gruppen und aggregierten Datensätze. Kann nur Daten aus einer einzelnen Tabelle zurückgeben. Erfahren Sie, wie Sie Daten mit der QueryByAttribute-Klasse abfragen
LINQ	Verwenden Sie OrganizationServiceContext.QueryProvider, um Abfragen mit der gängigen LINQ-Syntax zu verfassen. Alle LINQ-Abfragen werden in QueryExpression konvertiert, um die von Ihnen verwendeten Funktionen zu beschränken, die für `QueryExpression` verfügbar sind. Dieser Artikel konzentriert sich auf SDK-Klassen zum Abrufen von Daten. Erfahren Sie, wie Sie Daten mit LINQ abfragen (.NET Language-Integrated Query)

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:

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);
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:

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:

typ	Zurückgegebener Datentyp	Formatierte Wertbeschreibung
Ja/Nein BooleanAttributeMetadata	Boolesch	Die lokalisierte Bezeichnung für die entsprechenden BooleanOptionSetMetadata.FalseOption- oder BooleanOptionSetMetadata.TrueOption -Eigenschaften.
Kunde, Suche und Besitzender LookupAttributeMetadata	EntityReference	Der EntityReference.Name-Wert, bei dem es sich um den Wert der primären Namensspalte für den Datensatz handelt.
Datum und Uhrzeit DateTimeAttributeMetadata	DateTime	Hängt vom Verhalten und den Formatkonfigurationen für die Spalte, den Organisationseinstellungen und den von den Benutzenden festgelegten persönlichen Optionen ab, beispielsweise der Zeitzone, in sie sich aufhalten.
Entitätsname EntityNameAttributeMetadata	String	Wenn der Wert nicht `none` ist, ist der formatierte Wert der lokalisierte DisplayName-Wert für die Tabelle.
Währung MoneyAttributeMetadata	Finanzen	Hängt von der für die Spalte ausgewählten Währung sowie den Organisations- und Benutzereinstellungen ab.
Optionen MultiSelectPicklistAttributeMetadata	OptionSetValueCollection	Wenn eine einzelne Option ausgewählt ist, die lokalisierte Bezeichnung für die ausgewählte Option. Wenn mehrere Optionen ausgewählt sind, eine Zeichenfolge mit den lokalisierten Bezeichnungen für jede ausgewählte Option, getrennt durch `;` . Beispiel: `Appetizer; Entree; Dessert`
Option PicklistAttributeMetadata Status StateAttributeMetadata Statusgrund StatusAttributeMetadata	OptionSetValue	Die lokalisierte Bezeichnung für die ausgewählte Option.

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

Logischer Name	typ
`primarycontactid`	EntityReference
`createdon`	DateTime
`revenue`	Money
`statecode`	OptionSetValue

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:

Eigenschaften	typ	Beschreibung
`EntityLogicalName`	`String`	Der logische Name der Tabelle, welche die Spalte enthält, aus der die Daten stammen.
`AttributeLogicalName`	`String`	Der logische Name der Spalte, aus der die Daten stammen.
`Value`	`Object`	Der aggregierte Wert oder der Wert der Spaltenzeile unter Verwendung eines Alias.

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

Weitere Informationen zu Spaltenaliasen:

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.

Hinweis

Es gibt einige FetchXml-Funktionen, über die QueryExpression nicht verfügt. Beim Konvertieren einer FetchXml-Abfrage in QueryExpression gehen diese Unterschiede verloren. Erfahren Sie mehr über die Einschränkungen bei QueryExpression

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
};