Partage via

Interroger des données à l’aide de QueryExpression

La classe QueryExpression, ainsi que d’autres classes dans l’espace de noms Microsoft.Xrm.Sdk.Query, fournit un modèle objet pour composer des requêtes complexes pour récupérer des enregistrements à partir de Dataverse à l’aide de la méthode IOrganizationService.RetrieveMultiple. Comparez les options lors de l’interrogation de données à l’aide du SDK pour .NET

Composer une requête

Permet QueryExpression de composer des requêtes dynamiques que vous pouvez modifier sans la chaîne ou la manipulation XML requise lors de l’utilisation de FetchXml.

Toutes les requêtes sont basées sur une seule table. Utilisez la QueryExpression classe pour sélectionner la table à partir de laquelle la requête récupère les données.

Style d’initialisation d’objet

L’exemple suivant représente une requête simple QueryExpression qui retourne la colonne Name des cinq premières lignes de la table Account à l’aide de l’initialiseur d’objet afin que la requête soit définie dans une attribution unique.

public static EntityCollection SimpleExample(IOrganizationService service) {

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

   return service.RetrieveMultiple(query);
}

Lorsque vous initialisez l’instance de requête, vous pouvez :

Style d’attribution de propriété

Vous pouvez composer la même requête sans le constructeur QueryExpression(String) ou le style d’initialisation d’objet. Définissez simplement les propriétés sur l’instance instanciée, comme indiqué dans l’exemple suivant :

public static EntityCollection SimpleExample(IOrganizationService service)
{

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

   return service.RetrieveMultiple(query);
}

Cet exemple montre comment vous pouvez :

Les exemples de cette documentation utilisent une combinaison de styles d’initialisation d’objet et d’affectation de propriétés. À mesure que les requêtes deviennent plus complexes, le style d’initialisation des objets peut devenir fastidieux. Vous pouvez toujours définir les propriétés de la requête séparément et les ajouter à la requête en définissant les propriétés ou en utilisant les méthodes disponibles.

Limiter le nombre de lignes

Pour limitez le nombre de lignes renvoyées, utilisez la propriété QueryExpression.TopCount. Si vous ne définissez pas la TopCount propriété, Dataverse retourne jusqu’à 5 000 lignes pour les tables standard et 500 pour les tables élastiques.

Vous pouvez également spécifier un certain nombre d’enregistrements à retourner à l’aide de la pagination. N’utilisez pas la propriété TopCount lorsque vous demandez des pages de données. Découvrez comment demander des résultats paginés.

Vous ne pouvez pas utiliser la TopCount propriété lorsque vous demandez un nombre de lignes à l’aide de la propriété PagingInfo.ReturnTotalRecordCount. Apprenez à compter les lignes.

Renvoyer des résultats distincts

Utilisez le Propriété QueryExpression.Distinct pour exiger que la requête exclue toutes les valeurs en double dans les résultats.

Si vous utilisez la propriété Distinct, vous devez ajouter au moins une OrderExpression à la propriété QueryExpression.Orders pour avoir une pagination cohérente.

Lorsque vous utilisez le Distinct propriété, les résultats renvoyés n’incluent pas les valeurs de clé primaire pour chaque enregistrement car ils représentent une agrégation de toutes les valeurs distinctes.

Récupérer des données

Comme expliqué dans les données de requête à l’aide du Kit de développement logiciel (SDK) pour .NET, QueryExpression il s’agit de l’un des trois types dérivés de la classe QueryBase. Vous pouvez le transmettre à la méthode IOrganizationService.RetrieveMultiple pour obtenir un EntityCollection contenant les résultats.

EntityCollection results = service.RetrieveMultiple(query);

Astuce

Essayez d’utiliser l’ exemple de code QueryExpression pour utiliser cette méthode.

Vous pouvez également utiliser la classe RetrieveMultipleRequest pour définir la requête sur la propriété RetrieveMultipleRequest.Query. Ensuite, envoyez la requête à l’aide de la méthode IOrganizationService.Execute.

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

EntityCollection results = response.EntityCollection;

Utilisez la classe RetrieveMultipleRequest lorsque vous souhaitez :

Affiner votre requête

Après avoir sélectionné la table avec laquelle démarrer votre requête, affinez la requête pour obtenir les données nécessaires. Les articles suivants expliquent comment compléter votre requête.

Article Tâche
Sélectionner des colonnes. Spécifiez les colonnes de données à renvoyer.
Tables de jointure Spécifiez les tables associées à renvoyer dans les résultats.
Lignes de commande Spécifiez l’ordre de tri des lignes à renvoyer.
Lignes de filtre Spécifiez les lignes de données à renvoyer.
Résultats sur la page Spécifiez le nombre de lignes de données à renvoyer avec chaque requête.
Données agrégées Découvrez comment regrouper et agréger les données renvoyées.
Compter le nombre de lignes Découvrez comment obtenir un décompte du nombre de lignes renvoyées.
Optimisations des performances Comment optimiser les performances.

Limites

FetchXml prend en charge certaines fonctionnalités qui QueryExpression ne le sont pas.

Important

Si vous utilisez le FetchXmlToQueryExpression message avec la classe FetchXmlToQueryExpressionRequest du SDK ou la fonction Web API FetchXmlToQueryExpression, toutes les fonctionnalités qui QueryExpression ne prennent pas en charge ne sont pas appliquées et aucune erreur ne se produit.

Outils de la communauté

Le XrmToolBoxFetchXMLBuilder est un outil gratuit permettant de composer et de tester les requêtes FetchXml. Il génère également du code pour les requêtes QueryExpression à l’aide de la même expérience de concepteur.

Note

Microsoft ne prend pas en charge les outils créés par la communauté. Si vous avez des questions ou des problèmes avec les outils de la communauté, contactez l’éditeur de l’outil.

Utiliser QueryExpression comme paramètre de message

Vous pouvez également utiliser QueryExpression comme paramètre pour les opérations Dataverse, telles que les messages suivants :

Nom du message Classe de requête du SDK pour .NET Opération de l’API Web
BackgroundSendEmail BackgroundSendEmailRequest Action BackgroundSendEmail
BulkDetectDuplicates BulkDetectDuplicatesRequest Action BulkDetectDuplicates
BulkDelete BulkDeleteRequest Action BulkDelete
FullTextSearchKnowledgeArticle FullTextSearchKnowledgeArticleRequest Action FullTextSearchKnowledgeArticle
QueryExpressionToFetchXml QueryExpressionToFetchXmlRequest Action QueryExpressionToFetchXml
SendBulkMail SendBulkMailRequest Action SendBulkMail
SyncBulkOperation SyncBulkOperationRequest Action SyncBulkOperation
Rollup RollupRequest Fonction de cumul

Note

Les opérations d’API web autres que BulkDelete, SyncBulkOperation et QueryExpressionToFetchXml peuvent utiliser FetchXml via le type complexe FetchExpression. Bien que l’API web contienne les structures permettant de composer des requêtes à l’aide de QueryExpression types complexes QueryExpression, ColumnSet et FilterExpression, il n’existe actuellement aucun moyen d’utiliser ces structures pour récupérer des données QueryExpression à l’aide de l’API Web comme vous pouvez le faire avec FetchXml. Cette limitation signifie que vous ne pouvez pas tester les résultats de la requête que vous envoyez en tant que paramètre à l’aide de l’API web.

Étapes suivantes

Découvrez comment sélectionner les colonnes.

Sélectionner des colonnes.

Essayez quelques requêtes.

Exemple de code QueryExpression

  • Last updated on