Freigeben über

Daten mithilfe von QueryExpression abfragen

  • Artikel

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

Erstellen einer Abfrage

Verwenden Sie QueryExpression, um dynamische Abfragen zu erstellen, die Sie ohne die bei der Verwendung von FetchXml erforderliche Zeichenfolgen-/XML-Manipulation ändern können.

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, welch die Spalte „Name“ der ersten fünf Zeilen aus der Tabelle „Konto“ zurückgibt und dazu den Objektinitialisierer verwendet, sodass die Abfrage in einer einzigen Zuweisung festgelegt ist.

public static EntityCollection SimpleExample(IOrganizationService service) {

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

   return service.RetrieveMultiple(query);
}

Wenn die Abfrageinstanz initialisiert ist, können Sie:

Eigenschaftenzuweisungsstil

Sie können die gleiche Abfrage ohne den QueryExpression(String)-Konstruktor oder den Objektinitialisierungsstil erstellen und die Eigenschaften einfach auf die instanziierte Instanz festlegen, 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:

In den Beispielen dieser Dokumentation wird eine Kombination aus Objektinitialisierungs- und Eigenschaftenzuweisungsstilen verwendet. 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. Ohne Festlegen der TopCount Eigenschaft Dataverse werden bis zu 5.000 Zeilen zurückgegeben.

Alternativ können Sie mithilfe von Auslagerung eine Anzahl von Datensätzen angeben, die zurückgegeben werden sollen. Verwenden Sie die TopCount-Eigenschaft nicht, wenn Sie Seiten mit Daten anfordern. Erfahren Sie, wie Sie ausgelagerte Ergebnisse anfordern

Sie können die TopCount-Eigenschaft nicht verwenden, wenn Sie mit der PagingInfo.ReturnTotalRecordCount-Eigenschaft eine Zeilenanzahl anfordern. 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 Daten mit dem SDK für .NET abfragen erklärt, ist QueryExpression eine von drei von der QueryBase-Klasse abgeleiteten Arten. Sie können dies also an die IOrganizationService.RetrieveMultiple-Methode, um eine EntityCollection mit den Ergebnissen zu erhalten.

EntityCollection results = service.RetrieveMultiple(query);

Tipp

Versuchen Sie, diese Methode mit dem QueryExpression-Beispielcode zu verwenden.

Sie können auch die RetrieveMultipleRequest-Klasse verwenden. Legen Sie dazu die Abfrage auf die RetrieveMultipleRequest.Query-Eigenschaft fest, um die Anforderung mithilfe der IOrganizationService.Execute-Methode zu senden.

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:

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.

Artikel Aufgabe
Spalten auswählen Geben Sie an, welche Datenspalten zurückgegeben werden sollen.
Tabellen verbinden Geben Sie an, welche zugehörigen Tabellen in den Ergebnissen zurückgegeben werden sollen.
Bestellzeilen Geben Sie die Sortierreihenfolge der Zeilen an, die zurückgegeben werden sollen.
Filterzeilen Geben Sie an, welche Datenzeilen zurückgegeben werden sollen.
Seitenergebnisse Geben Sie an, wie viele Datenzeilen mit jeder Anforderung zurückgegeben werden sollen.
Aggregatdaten So gruppieren und aggregieren Sie die zurückgegebenen Daten.
Anzahl der Zeilen So ermitteln Sie die Anzahl der zurückgegebenen Zeilen.
Leistungsoptimierungen So optimieren Sie die Leistung

Einschränkungen

Sie können mit FetchXml einige Dinge tun, die QueryExpression nicht unterstützt.

Wichtig

Wenn Sie die FetchXmlToQueryExpression-Nachricht entweder mit der SDK-FetchXmlToQueryExpressionRequest-Klasse oder der Web-API-FetchXmlToQueryExpression-Funktion verwenden, werden alle von QueryExpression nicht unterstützten Funktionen nicht angewendet und es tritt kein Fehler auf.

Community-Tools

Die XrmToolBox FetchXMLBuilder ist ein kostenloses Tool zum Erstellen und Testen von FetchXml-Anforderungen, generiert aber auch Code für QueryExpression-Abfragen mit derselben Designererfahrung.

Hinweis

Von der Community erstellte Tools werden von Microsoft nicht unterstützt. Wenn Sie Fragen oder Probleme mit Community-Tools haben, wenden Sie sich an den Herausgeber des Tools.

QueryExpression als Nachrichtenparameter verwenden

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

Name der Nachricht SDK für die .NET-Anforderungsklasse Web-API-Vorgang
BackgroundSendEmail BackgroundSendEmailRequest BackgroundSendEmail-Aktion
BulkDetectDuplicates BulkDetectDuplicatesRequest BulkDetectDuplicates-Aktion
BulkDelete BulkDeleteRequest BulkDelete-Aktion
FullTextSearchKnowledgeArticle FullTextSearchKnowledgeArticleRequest FullTextSearchKnowledgeArticle-Aktion
QueryExpressionToFetchXml QueryExpressionToFetchXmlRequest QueryExpressionToFetchXml-Aktion
SendBulkMail SendBulkMailRequest SendBulkMail-Aktion
SyncBulkOperation SyncBulkOperationRequest SyncBulkOperation-Aktion
Rollup RollupRequest Rollup-Funktion

Hinweis

Andere Web-API-Vorgänge als BulkDelete, SyncBulkOperation und die QueryExpressionToFetchXml-Aktion können FetchXml über den komplexen FetchExpression-Typ verwenden. Die Web-API enthält zwar die Strukturen zum Erstellen von Abfragen mithilfe von QueryExpression, etwa die komplexen Typen QueryExpression, ColumnSet und FilterExpression, es gibt jedoch derzeit keine Möglichkeit, diese zum Abrufen von Daten mit QueryExpression mithilfe der Web-API zu verwenden, wie mit FetchXml möglich. Dies bedeutet, dass es nicht möglich ist, die Ergebnisse der Abfrage zu testen, die Sie mithilfe der Web-API als Parameter senden würden.

Nächste Schritte,

Lernen Sie, wie man Spalten auswählt.

Spalten auswählen

Probieren Sie einige Abfragen aus.

QueryExpression-Beispielcode