Interroger les données à l’aide du SDK pour .NET

  • Article

Le SDK pour .NET fournit plusieurs méthodes pour interroger les données. Chacune présente différents avantages.

Méthode Avantages
FetchExpression Utilisez le langage d’interrogation propriétaire FetchXML pour créer des requêtes complexes qui renvoient des agrégats, tels que la somme d’une valeur pour l’ensemble des enregistrements renvoyés. Vous pouvez également effectuer des opérations de regroupement avec FetchXML. Peut inclure des données de lignes de table liées (enregistrements d’entité).
QueryExpression Vous avez un modèle d’objet fortement typé pour créer des requêtes complexes. Prend en charge toutes les fonctionnalités dans FetchXML à l’exception des agrégats et du groupement. Peut inclure des données de lignes de table liées (enregistrements d’entité).
QueryByAttribute Un modèle d’objet plus simple que QueryExpression. Utiliser QueryByAttribute pour les requêtes où vous testez si tous les critères de valeur de colonne de table (attribut) dans votre requête correspondent. Ne peut renvoyer que les données d’une seule table (type d’entité).
LINQ Utilisez OrganizationServiceContext.QueryProvider pour composer des requêtes à l’aide de la syntaxe populaire de LINQ. Toutes les demandes LINQ sont converties en QueryExpression de telle sorte que les capacités sont limitées à celles disponibles pour QueryExpression
Cette rubrique se concentre sur les styles de requêtes disponibles via les classes d’assembly du SDK. Pour plus d’informations : Générer des requêtes avec LINQ (Language-Integrated .NET Query).

FetchExpressionQueryExpression etQueryByAttribute proviennent de la classe abstraite QueryBase. Il existe deux méthodes différentes pour obtenir les résultats d’une requête définie à l’aide de ces classes :

Notes

La méthode IOrganizationService.RetrieveMultiple est généralement la méthode préférée. Il n’y a pas de fonctionnalités spéciales qui exigent d’utiliser la classe RetrieveMultipleRequest.

Chacune de ces méthodes renvoie une EntityCollection qui contient les résultats de la requête dans la collection Entities ainsi que les propriétés pour gérer des requêtes supplémentaires pour recevoir des résultats paginés.

Notes

Pour garantir les meilleures performances, chaque requête de requête peut renvoyer un maximum de 5 000 lignes. Pour renvoyer davantage d’ensembles de résultats, vous devez demander des pages supplémentaires.

Toutes les conditions de filtre pour les valeurs de chaîne sont insensibles à la casse.

Les valeurs de colonne de table nulles ne sont pas renvoyées

Lorsqu’une colonne de table (attribut d’entité) contient une valeur nulle, ou si l’attribut n’était pas inclus dans les attributs FetchXml ou le ColumnSet, la collection Entity.Attributes n’inclut pas l’attribut. Il n’existe pas de clé pour y accéder ni une valeur à renvoyer. L’absence de l’attribut indique qu’elle est nulle. Lors de l’utilisation du style lié au début, les propriétés de classe Entity générées géreront cela et renverront une valeur nulle.

En cas d’utilisation du style de liaison tardive, si vous essayez d’accéder à la valeur avec un indexeur sur les collections Attributes ou FormattedValues, vous obtenez une KeyNotFoundException avec le message The given key was not present in the dictionary.

Pour éviter cela lors de l’utilisation du style de liaison tardive, vous pouvez utiliser deux stratégies :

  1. Pour un attribut susceptible d’être nul, utilisez la méthode Entity.Contains(String) pour vérifier si l’attribut est nul avant d’essayer d’y accéder avec un indexeur. Par exemple :

    Money revenue = (entity.Contains("revenue")? entity["revenue"] : null);

  2. Utilisez Entity.GetAttributeValue<T>(String) pour accéder à la valeur. Par exemple :

    Money revenue = entity.GetAttributeValue<Money>();

Notes

Si le type spécifié avec GetAttributeValue<T>(String) est un type de valeur qui ne peut pas être nul, comme Boolean ou DateTime, la valeur renvoyée est la valeur par défaut, comme false ou 1/1/0001 12:00:00 AM plutôt que null.

Utiliser FetchXML avec FetchExpression

FetchXml est un langage de requête propriétaire basé sur XML qui peut être utilisé avec les requêtes d’assembly du SDK avec FetchExpression et par l’API Web à l’aide de la chaîne de requête fetchXml. Plus d’informations : Interroger des données à l’aide de FetchXml

L’exemple suivant montre une requête simple pour renvoyer jusqu’à 50 lignes de compte correspondantes où la valeur address1_city est égale à Redmond, ordonnée par name.

string fetchXml = @"
<fetch top='50' >
  <entity name='account' >
    <attribute name='name' />
    <filter>
      <condition 
        attribute='address1_city' 
        operator='eq' 
        value='Redmond' />
    </filter>
    <order attribute='name' />
  </entity>
</fetch>";

var query = new FetchExpression(fetchXml);

EntityCollection results = svc.RetrieveMultiple(query);

results.Entities.ToList().ForEach(x => {
  Console.WriteLine(x.Attributes["name"]);
});

Important

Lors de la récupération des lignes du tableau, vous ne devez demander que les valeurs de colonne dont vous avez besoin en définissant les attributs spécifiques à l’aide des éléments attribute plutôt que d’utiliser les éléments all-attributes pour renvoyer tous les attributs.

Pour plus d’informations :

Utiliser QueryExpression

La classe QueryExpression fournit une série d’objets fortement typés qui est optimisée pour la manipulations d’exécution des requêtes.

L’exemple suivant montre une requête simple pour renvoyer jusqu’à 50 lignes de compte correspondantes où la valeur address1_city est égale à Redmond, ordonnée par name.

var query = new QueryExpression("account")
{
  ColumnSet = new ColumnSet("name"),
  Criteria = new FilterExpression(LogicalOperator.And),
  TopCount = 50
};
query.Criteria.AddCondition("address1_city", ConditionOperator.Equal, "Redmond");
query.AddOrder("name", OrderType.Ascending);

EntityCollection results = svc.RetrieveMultiple(query);

results.Entities.ToList().ForEach(x =>
{
  Console.WriteLine(x.Attributes["name"]);
});

Important

Lors de la récupération de lignes, vous ne devez demander que les valeurs de colonne dont vous avez besoin en définissant les attributs spécifiques à l’aide du constructeur de classe ColumnSet. Même si le constructeur de classe ColumnSet fournit une surcharge qui accepte un paramètre allColumns booléen, vous ne devez pas l’utiliser dans le code de production.

Pour plus d’informations :

Utiliser QueryByAttribute

La classe QueryByAttribute fournit un ensemble d’objets fortement typé qui est optimisé pour les requêtes simples et courantes de lignes de table. Contrairement à FetchXML et QueryExpression, QueryByAttribute ne peut renvoyer que les données d’une seule table. Il ne permet pas de récupérer des données à partir de lignes de table associées ou de critères de requête complexes.

L’exemple suivant montre une requête simple pour renvoyer jusqu’à 50 lignes de compte correspondantes où la valeur address1_city est égale à Redmond, ordonnée par name.

var query = new QueryByAttribute("account")
{
  TopCount = 50,
  ColumnSet = new ColumnSet("name")
};
query.AddAttributeValue("address1_city", "Redmond");
query.AddOrder("name", OrderType.Ascending);

EntityCollection results = svc.RetrieveMultiple(query);

results.Entities.ToList().ForEach(x =>
{
  Console.WriteLine(x.Attributes["name"]);
});

Pour plus d’informations :

Accéder aux valeurs formatées

Quelle que soit la méthode que vous utilisez pour interroger les tables, les données seront renvoyées sous la forme EntityCollection.Entities. Vous pouvez accéder aux valeurs de données de la colonne (attribut) du tableau à l’aide de la collection Entity.Attributes . Mais ces valeurs peuvent être d’un autre type que la chaîne dont vous auriez besoin pour manipuler afin d’obtenir les valeurs de chaînes que vous pouvez afficher dans votre application.

Vous pouvez accéder aux valeurs de chaîne qui utilisent les paramètres d’environnements pour le formatage à l’aide des valeurs dans la collection Entity.FormattedValues .

L’exemple suivant présente comment accéder aux valeurs de chaîne formatées pour les attributs de compte suivants :

Nom logique de l’attribut Type
primarycontactid EntityReference
createdon DateTime
revenue Money
statecode OptionSetValue 
var query = new QueryByAttribute("account")
{
TopCount = 50,
ColumnSet = new ColumnSet("name", "primarycontactid", "createdon", "revenue", "statecode")
};
query.AddAttributeValue("address1_city", "Redmond");
query.AddOrder("name", OrderType.Ascending);

EntityCollection results = svc.RetrieveMultiple(query);

results.Entities.ToList().ForEach(x =>
{
Console.WriteLine(@"
name:{0}
primary contact: {1}
created on: {2}
revenue: {3}
status: {4}",
  x.Attributes["name"],
  (x.Contains("primarycontactid")? x.FormattedValues["primarycontactid"]:string.Empty),
  x.FormattedValues["createdon"],
  (x.Contains("revenue") ? x.FormattedValues["revenue"] : string.Empty),
  x.FormattedValues["statecode"]
  );
});

Notes

Les colonnes de table (attributs) qui contiennent des valeurs nulles ne sont pas renvoyées dans la requête Attributes ou les collections FormattedValues. Si une colonne peut contenir une valeur nulle, vous devez vérifier en utilisant la méthode Contains avant d’essayer d’accéder à la valeur.

Les résultats formatés s’afficheraient comme suit :

name:A Datum (sample)
  primary contact: Rene Valdes (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $10,000.000
  status: Active

name:City Power & Light (sample)
  primary contact: Scott Konersmann (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $100,000.000
  status: Active

name:Contoso Pharmaceuticals (sample)
  primary contact: Robert Lyon (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $60,000.000
  status: Active

Convertir des requêtes entre des expressions FetchXML et QueryExpression

Vous pouvez convertir les requêtes QueryExpression en requêtes FetchXml et FetchXml et QueryExpression à l’aide des classes QueryExpressionToFetchXmlRequest et FetchXmlToQueryExpressionRequest.

La table SavedQuery stocke les vues système d’une table (type d’entité) et la table UserQuery stocke les requêtes utilisateur enregistrées. D’autres tables peuvent également stocker une requête sous forme de chaîne FetchXml. Ces méthodes permettent de convertir une chaîne FetchXML vers QueryExpression, de telle sorte qu’elle peut être manipulée à l’aide du modèle d’objet, puis reconvertie vers FetchXml de telle sorte qu’elle peut être enregistrée comme chaîne.

Pour plus d’informations : Exemple : Convertir des requêtes entre des expressions Fetch et Query

Limites des conditions de requête

Dataverse a une limite de 500 conditions au total autorisées dans une requête. Toutes les jointures incluses dans la requête sont comptées dans le cadre de cette limite. Si une requête (et ses jointures) dépasse 500 conditions, l’utilisateur recevra l’erreur suivante lorsque la requête est exécutée : "Le nombre de conditions dans la requête a dépassé la limite maximale".

Si cela se produit, un utilisateur doit soit :

  • Réduire le nombre de conditions dans sa requête.
  • Utiliser la clause In, qui autorise les GUID et les chaînes jusqu’à 850 caractères sans limite d’entiers.

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).