Abfragen von Daten mithilfe von QueryExpression

Die QueryExpression-Klasse stellt zusammen mit anderen Klassen im Microsoft.Xrm.Sdk.Query-Namespace ein Objektmodell zum Verfassen komplexer Abfragen zum Abrufen von Datensätzen aus Dataverse mithilfe der IOrganizationService.RetrieveMultiple-Methode bereit. Vergleichen Sie die Optionen beim Abfragen von Daten mit dem SDK für .NET

Erstellen einer Abfrage

Wird QueryExpression verwendet, um dynamische Abfragen zu verfassen, die Sie ohne die Zeichenfolge oder XML-Manipulation ändern können, die bei Verwendung von FetchXml erforderlich ist.

Alle Abfragen basieren auf einer einzigen Tabelle. Verwenden Sie die QueryExpression-Klasse, um die Tabelle auszuwählen, aus der die Abfrage Daten abruft.

Objektinitialisierungsstil

Das folgende Beispiel stellt eine einfache QueryExpression Abfrage dar, die die Namensspalte der ersten fünf Zeilen aus der Account-Tabelle unter Verwendung des Objekt-Initialisierers zurückgibt, sodass die Abfrage in einem einzigen Ausdruck definiert wird.

public static EntityCollection SimpleExample(IOrganizationService service) {

   QueryExpression query = new("account")
   {
         ColumnSet = new ColumnSet("name"),
         TopCount = 5
   };

   return service.RetrieveMultiple(query);
}

Wenn Sie die Abfrageinstanz initialisieren, können Sie:

• Geben Sie die Tabelle als QueryExpression.EntityName-Eigenschaft mithilfe des QueryExpression(String)-Konstruktors an.
• Die zurückzugebenden Spalten festlegen, indem Sie die QueryExpression.ColumnSet-Eigenschaft festlegen, indem Sie ein neues ColumnSet instanziieren und einen oder mehrere LogicalName-Spaltenwerte an den ColumnSet(String[]) Konstruktor übergeben. Erfahren Sie mehr über das Auswählen von Spalten.
• Beschränken Sie die Anzahl der Datensätze, die zurückgegeben werden, indem Sie die QueryExpression.TopCount-Eigenschaft festlegen.

Eigenschaftszuweisungsstil

Sie können dieselbe Abfrage ohne den QueryExpression(String)-Konstruktor oder die Objektinitialisierungsart verfassen. Legen Sie einfach die Eigenschaften für die instanziierte Instanz fest, wie im folgenden Beispiel gezeigt:

public static EntityCollection SimpleExample(IOrganizationService service)
{

   QueryExpression query = new();
   query.EntityName = "account";
   query.ColumnSet.AddColumn("name");
   query.TopCount = 5;

   return service.RetrieveMultiple(query);
}

Dieses Beispiel zeigt, wie Sie Folgendes tun können:

• Geben Sie die Tabelle direkt nach der Initialisierung der Instanz mithilfe des Standardkonstruktors als QueryExpression an.
• Die zurückzugebenden Spalten festlegen, indem Sie QueryExpression.ColumnSet mit der ColumnSet.AddColumn-Methode festlegen, um den Spaltennamen hinzuzufügen. Erfahren Sie mehr über das Auswählen von Spalten.
• Grenzen Sie die Anzahl der zurückgegebenen Datensätze ein, indem Sie die QueryExpression.TopCount-Eigenschaftnach der Objektinitialisierung festlegen.

Beispiele in dieser Dokumentation verwenden eine Kombination aus Objektinitialisierungs- und Eigenschaftszuweisungsformatvorlagen. Wenn die Abfragen komplexer werden, kann der Objektinitialisierungsstil unhandlich werden. Sie können die Abfrageeigenschaften jederzeit separat festlegen und sie der Abfrage hinzufügen, indem Sie die Eigenschaften festlegen oder die verfügbaren Methoden verwenden.

Beschränken der Anzahl von Zeilen

Um die Anzahl der zurückgegebenen Zeilen einzugrenzen, verwenden Sie die QueryExpression.TopCount-Eigenschaft. Wenn Sie die TopCount Eigenschaft nicht festlegen, gibt Dataverse bis zu 5.000 Zeilen für Standardtabellen und 500 für elastische Tabellen zurück.

Geben Sie alternativ eine Anzahl von Datensätzen an, die mithilfe von Paging zurückgegeben werden sollen. Verwenden Sie die TopCount-Eigenschaft nicht, wenn Sie Seiten mit Daten anfordern. Erfahren Sie, wie Sie seitenseitige Ergebnisse anfordern.

Sie können die TopCount Eigenschaft nicht verwenden, wenn Sie eine Anzahl von Zeilen anfordern, indem Sie die PagingInfo.ReturnTotalRecordCount-Eigenschaft verwenden. Erfahren Sie, wie Sie Zeilen zählen.

Bestimmte Ergebnisse zurückgeben

Verwenden Sie die QueryExpression.Distinct-Eigenschaft, damit die Abfrage alle doppelten Werte in den Ergebnissen ausschließt.

Wenn Sie die Distinct-Eigenschaft verwenden, müssen Sie der QueryExpression.Orders-Eigenschaft mindestens eine OrderExpression hinzufügen, um ein einheitliches Paging zu gewährleisten.

Wenn Sie die Distinct-Eigenschaft verwenden, enthalten die zurückgegebenen Ergebnisse nicht die Primärschlüsselwerte für die einzelnen Datensätze, da sie eine Aggregation aller eindeutigen Werte darstellen.

Daten abrufen

Wie in Abfragedaten mit dem SDK für .NET erläutert, handelt es sich um einen von drei Typen, QueryExpression die von der QueryBase-Klasse abgeleitet werden. Sie können es an die IOrganizationService.RetrieveMultiple-Methode übergeben, um ein enthaltenes EntityCollection Ergebnis abzurufen.

EntityCollection results = service.RetrieveMultiple(query);

Sie können auch die RetrieveMultipleRequest-Klasse verwenden, um die Abfrage auf die RetrieveMultipleRequest.Query-Eigenschaft festzulegen. Senden Sie dann die Anforderung mithilfe der IOrganizationService.Execute-Methode.

RetrieveMultipleRequest request = new()
{
      Query = query
};
var response = (RetrieveMultipleResponse)service.Execute(request);

EntityCollection results = response.EntityCollection;

Verwenden Sie die RetrieveMultipleRequest-Klasse, wenn Sie Folgendes tun möchten:

• Einen optionalen Parameter mit der Anforderung senden
• Schließen Sie den Vorgang als Teil eines Batches mithilfe der ExecuteMultipleRequest - oder ExecuteTransactionRequest-Klassen ein.

Abfrage verfeinern

Nachdem Sie die Tabelle ausgewählt haben, mit der Ihre Abfrage beginnen soll, verfeinern Sie die Abfrage, um die benötigten Daten zu erhalten. In den folgenden Artikeln wird erläutert, wie Sie Ihre Abfrage vervollständigen.

Einschränkungen

FetchXml unterstützt einige Funktionen, die QueryExpression nicht.

• Abrufen von Daten mithilfe der Dataverse-Web-API. Einige Web-API-Vorgänge ermöglichen QueryExpression Parameter, aber Sie können keine Abfrage zusammenstellen, indem Sie QueryExpression verwenden, um Daten über die Web-API abzurufen.

• Aggregationseinschränkungen listen die folgenden Einschränkungen für Aggregationen mithilfe von QueryExpression:

  • Eindeutige Zahlen mit CountColumn erhalten
  • Zeitzone beim Gruppieren nach Datum
  • Zeilenaggregat
  • Limit pro Abfrage

• Tabellenübergreifende Spaltenvergleiche durchführen. QueryExpression unterstützt das Filtern nach Spaltenwerten in derselben Zeile, diese müssen sich jedoch in derselben Tabelle befinden.

• Sie können die Standardsortierreihenfolge für Auswahlspalten nicht außer Kraft setzen.

• Sie können die Leistungsoptimierung „Late Materialize“-Abfrage nicht verwenden.

Community-Werkzeuge

Das XrmToolBoxFetchXMLBuilder ist ein kostenloses Tool zum Verfassen und Testen von FetchXml-Anforderungen. Außerdem wird Code für QueryExpression Abfragen generiert, indem die gleiche Designerumgebung verwendet wird.

QueryExpression als Nachrichtenparameter verwenden

Sie können auch als Parameter für Dataverse-Vorgänge wie die folgenden Meldungen verwenden QueryExpression :

Nächste Schritte,

Lernen Sie, wie man Spalten auswählt.

Probieren Sie einige Abfragen aus.