Partager via

Interroger les données à l’aide de QueryExpression

  • Article

La classe QueryExpression, ainsi que d’autres classes de l’ espace de noms Microsoft.Xrm.Sdk.Query, fournit un objet modèle pour composer des requêtes complexes afin de récupérer des enregistrements 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

Utilisez QueryExpression pour composer des requêtes dynamiques que vous pouvez modifier sans la manipulation de chaîne/xml requise à l’aide 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 simple QueryExpression requête qui renvoie la colonne Nom des cinq premières lignes de la table de compte en utilisant l’ initialiseur d’objet afin que la requête soit définie dans une seule affectation.

public static EntityCollection SimpleExample(IOrganizationService service) {

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

   return service.RetrieveMultiple(query);
}

Lorsque l’instance de requête est initialisée, 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 et définir 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 utiliseront une combinaison de styles d’initialisation d’objet et d’attribution 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. Sans définir la TopCount propriété, Dataverse renvoie jusqu’à 5 000 lignes.

Sinon, spécifiez un certain nombre d’enregistrements à renvoyer en utilisant 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 propriété TopCount lorsque vous demandez un nombre de lignes à l’aide de la propriété PagingInfo.ReturnTotalRecordCount. Découvrez comment compter des 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 le Distinct propriété, vous devez ajouter au moins un ExpressiondeCommande au 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 Interroger des données à l’aide du SDK pour .NET, QueryExpression est l’un des trois types dérivés du Classe QueryBase, afin que vous puissiez le transmettre au Méthode IOrganizationService.RetrieveMultiple pour obtenir un EntityCollection contenant les résultats.

EntityCollection results = service.RetrieveMultiple(query);

Conseil

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

Vous pouvez également utiliser la classe RetrieveMultipleRequest définir la requête sur la propriété RetrieveMultipleRequest.Query pour envoyer 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.
Joindre des tables Spécifiez les tables associées à renvoyer dans les résultats.
Trier des lignes Spécifiez l’ordre de tri des lignes à renvoyer.
Filtrer des lignes Spécifiez les lignes de données à renvoyer.
Paginer les résultats Spécifiez le nombre de lignes de données à renvoyer avec chaque requête.
Agréger des donné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 Découvrez comment optimiser les performances

Limitations

Il y a certaines choses que vous pouvez faire en utilisant FetchXml et qui QueryExpression ne sont pas prises en charge.

Important

Si vous utilisez le FetchXmlToQueryExpression message avec la classe SDK FetchXmlToQueryExpressionRequest ou l’API Web fonction FetchXmlToQueryExpression, toutes les fonctionnalités non prises en charge par QueryExpression ne sont pas appliquées et il n’y aura pas d’erreur.

Outils de la communauté

Le XrmToolBox FetchXMLBuilder est un outil gratuit pour composer et tester des requêtes FetchXml, mais il génère également du code pour QueryExpression requêtes en utilisant la même expérience de designer.

Notes

Les outils créés par la communauté ne sont pas pris en charge par Microsoft. 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 utilisez également QueryExpression comme paramètre pour Dataverse opérations 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 BulkDelete action
FullTextSearchKnowledgeArticle FullTextSearchKnowledgeArticleRequest Action FullTextSearchKnowledgeArticle
QueryExpressionToFetchXml QueryExpressionToFetchXmlRequest Action QueryExpressionToFetchXml
SendBulkMail SendBulkMailRequest Action SendBulkMail
SyncBulkOperation SyncBulkOperationRequest SyncBulkOperation action
Rollup RollupRequest Fonction de cumul

Notes

Opérations d’API Web autres que BulkDelete, SyncBulkOperation et action QueryExpressionToFetchXml peut utiliser FetchXml via le type complexe FetchExpression. Alors que l’API Web contient les structures permettant de composer des requêtes à l’aide de QueryExpression, telles que QueryExpression, ColumnSet et FilterExpression types complexes, il n’existe actuellement aucun moyen de les utiliser pour récupérer des données avec QueryExpression à l’aide de l’API Web comme vous pouvez le faire avec FetchXml. Cela signifie qu’il n’est pas possible de tester les résultats de la requête que vous enverriez en 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