Interroger les données à l’aide de QueryExpression

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 :

• Spécifiez la table en tant que propriété QueryExpression.EntityName à l’aide du constructeur QueryExpression(String).
• Spécifiez les colonnes à renvoyer en définissant la propriété QueryExpression.ColumnSet en instanciant un nouveau ColumnSet et en transmettant un ou plusieurs column LogicalName valeurs au constructeur ColumnSet(String[]). En savoir plus sur la sélection des colonnes
• Limitez le nombre d’enregistrements renvoyés en définissant la propriété QueryExpression.TopCount

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 :

• Spécifiez la table en tant que propriété QueryExpression.EntityName directement après avoir initialisé l’ QueryExpression instance à l’aide du constructeur par défaut.
• Spécifiez les colonnes à renvoyer en définissant la QueryExpression.ColumnSet à l’aide de la méthode ColumnSet.AddColumn pour ajouter le nom de la colonne. . En savoir plus sur la sélection des colonnes
• Limitez le nombre d’enregistrements renvoyés en définissant la propriété QueryExpression.TopCount après l’initialisation d’objet.

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

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 :

• Envoyer de paramètres facultatifs avec la requête
• Incluez l’opération dans le cadre d’un lot à l’aide des classes ExecuteMultipleRequest ou ExecuteTransactionRequest .

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.

Limitations

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

• Récupérer des données à l’aide de l’API web Dataverse. Certaines opérations de l’API Web activent QueryExpression des paramètres, mais vous ne pouvez pas composer une requête en utilisant QueryExpression pour récupérer des données à l’aide de l’option API Web.

• Limitations d’agrégation répertorie les limitations suivantes pour les agrégations utilisant QueryExpression :

  • Obtenez un numéro distinct avec CountColumn
  • Fuseau horaire lors du regroupement par date
  • Agrégation de lignes
  • Limite par requête

• Effectuez des comparaisons croisées de colonnes de tableaux. QueryExpression prend en charge le filtrage sur les valeurs de colonne dans la même ligne, mais elles doivent se trouver dans la même table.

• Vous ne pouvez pas remplacer l’ordre de tri par défaut pour les colonnes de choix

• Vous ne pouvez pas utiliser l’optimisation des performances de la requête Late Materialise .

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.

Utiliser QueryExpression comme paramètre de message

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

Étapes suivantes

Découvrez comment sélectionner les colonnes.

Essayez quelques requêtes.