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

Article
07/22/2024

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

méthode	Avantages
Classe FetchExpression	Utilisez le propriétaire FetchXML langage de requête pour créer des requêtes complexes pouvant renvoyer des ensembles de données paginées ou des données groupées et agrégées. Vous pouvez créer des jointures pour inclure des données provenant d’enregistrements associés. FetchXml offre des fonctionnalités que les autres options n’offrent pas. Découvrez comment interroger des données à l’aide de FetchXml
classe QueryExpression	Utilisez le modèle d’objet fortement typé pour créer des requêtes complexes pouvant renvoyer des ensembles de données paginées ou des données groupées et agrégées. Vous pouvez créer des jointures pour inclure des données provenant d’enregistrements associés. Les soutiens la plupart des fonctionnalités dans FetchXML. Apprenez à interroger les données à l'aide de QueryExpression
Classe QueryByAttribute	Un modèle objet plus simple pour les requêtes courantes afin de renvoyer des lignes qui correspondent à tous les critères de votre requête. Prend en charge la pagination, mais pas les groupes et les ensembles de données agrégées. Ne peut renvoyer que les données d’une seule table. Découvrez comment interroger des données à l’aide de la classe QueryByAttribute
LINQ	Utiliser OrganizationServiceContext.QueryProvider pour composer des requêtes en utilisant la syntaxe populaire LINQ. Toutes les demandes LINQ sont converties en QueryExpression de telle sorte que les capacités sont limitées à celles disponibles pour `QueryExpression`. Cet article se concentre sur les classes du SDK pour récupérer des données. Découvrez comment interroger données LINQ (requête Language-Integrated .NET)

Comment envoyer des demandes

FetchExpression QueryExpression 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 :

Vous pouvez passer une instance de l’une de ces classes en tant que paramètre query vers la méthode IOrganizationService.RetrieveMultiple.
Vous pouvez définir la propriété RetrieveMultipleRequest.Query de la classe et utiliser la méthode IOrganizationService.Execute .

Généralement, les gens utilisent la méthode IOrganizationService.RetrieveMultiple , mais vous pouvez utiliser la classe RetrieveMultipleRequest pour utiliser paramètres facultatifs ou pour envoyer la requête dans le cadre d’un lot à l’aide de ExecuteMultipleRequest ou ExecuteTransactionRequest cours.

Ces deux méthodes renvoient un EntityCollection qui contient les résultats de la requête dans la Entities propriété de collection. EntityCollection possède d’autres propriétés pour gérer les résultats de pagination renvoyés.

Lorsque vous récupérez des données à l’aide de ces classes, vous devez comprendre certains concepts. Le reste de cet article explique les concepts courants lors de la récupération de données à l’aide du SDK pour les classes .NET.

Les valeurs de colonne nulles ne sont pas renvoyées

Lorsqu’une colonne de table (attribut d’entité) contient une valeur nulle, ou si la colonne n’a pas été demandée, la collection Entity.Attributes n’inclura pas la valeur. Il n’existe ni clé pour y accéder ni une valeur à renvoyer. L’absence de l’attribut indique qu’elle est nulle.

Les colonnes qui ne sont pas valides en lecture renvoient toujours des valeurs nulles. La définition de ces colonnes a la propriété AttributeMetadata.IsValidForRead définie sur false.

Les premières classes liées gèrent les valeurs nulles

Lorsque vous utilisez le style de liaison anticipée, les propriétés des classe générées héritent de classe entité gèrent cela et renvoient une valeur nulle. En savoir plus sur la génération de classes liées précocement

Comment atténuer les valeurs nulles à l’aide de classes liées tardivement

Lorsque vous utilisez le style de liaison tardive, si vous essayez d’accéder à la valeur à l’aide d’un indexeur sur Entity.Attributes ou collections Entity.FormattedValues , vous recevrez un KeyNotFoundException avec ce message : The given key was not present in the dictionary.

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

Pour une colonne qui pourrait être nulle, utilisez la méthode Entity.Contains(System.String) pour vérifier si la valeur de la colonne est nulle avant de tenter d’y accéder avec un indexeur. Par exemple :

Money revenue = (entity.Contains("revenue")? entity["revenue"] : null);
Utilisez la méthode Entity.GetAttributeValue<T>(System.String) pour accéder à la valeur. Par exemple :

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

Notes

Si le type spécifié avec Entity.GetAttributeValue<T>(System.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.

Chaque requête peut renvoyer jusqu’à 5 000 enregistrements

Les applications interactives limitent généralement le nombre d’enregistrements affichés à un nombre avec lequel un humain peut interagir, puis offrent la possibilité de parcourir les pages de données. Par exemple, les applications basées sur un modèle dépendent d’une option personnelle qui permet aux utilisateurs de choisir une valeur comprise entre 25 et 250. Ces informations sont stockées dans UserSettings.PagingLimit colonne.

Les applications qui récupèrent des données Dataverse sans afficher les données dans une application n’ont pas besoin de spécifier une taille de page. La taille de page par défaut et maximale est de 5 000 lignes. Si vous ne définissez pas de taille de page, Dataverse renverra jusqu’à 5 000 lignes de données à la fois. Pour obtenir plus de lignes, vous devez envoyer des requêtes supplémentaires.

La pagination fonctionne mieux lorsque vous utilisez les données du cookie de pagination qui Dataverse renvoient avec la propriété EntityCollection.PagingCookie , mais cela n’est pas obligatoire et certaines requêtes le feront. ne renvoie pas de valeur de cookie de pagination. En savoir plus :

Les valeurs formatées sont renvoyées pour certaines colonnes

Pour chaque Entité dans le EntityCollection.Entities, accédez aux valeurs de données de la colonne du tableau (attribut) à l’aide du Collection Entity.Attributes .

Vous pouvez afficher et modifier des types de données simples tels que des nombres et des chaînes directement dans les applications. Pour certains types de données, Dataverse fournit des valeurs de chaîne formatées en lecture seule que vous pouvez afficher dans les applications. Le format de certaines de ces valeurs de chaîne dépend des paramètres qui peuvent être définis par un Administrateur et remplacés par chaque utilisateur.

Un Administrateur peut personnaliser les options régionales par défaut qui s’appliquent à tous les nouveaux utilisateurs. Ces paramètres sont stockés dans la table de l’organisation.
Chaque utilisateur peut remplacer ces paramètres par ses préférences personnelles. Ces paramètres sont stockés dans la table UserSettings.

Utilisez la collection Entity.FormattedValues pour accéder aux valeurs formatées pour ces types de colonnes :

Type	Type de données Renvoyer	Description de la Valeur mise en forme
Oui/Non BooleanAttributeMetadata	Booléen	Étiquette localisée pour les propriétés BooleanOptionSetMetadata.FalseOption ou BooleanOptionSetMetadata.TrueOption correspondantes.
Client, Recherche et Propriétaire LookupAttributeMetadata	EntityReference	La EntityReference.Name valeur, qui est la valeur de la colonne de nom principale de l’enregistrement.
Date et heure DateTimeAttributeMetadata	Date/Heure	Dépend du des configurations de comportement et de format de la colonne, des paramètres de l’organisation et des options personnelles définies par l’utilisateur, telles que le fuseau horaire dans lequel il se trouve.
Nom de l’entité EntityNameAttributeMetadata	Chaîne	Lorsque la valeur n’est pas `none`, la valeur formatée est la valeur DisplayName localisée pour la table.
Devise MoneyAttributeMetadata	Argent	Dépend de la devise sélectionnée pour la colonne ainsi que des préférences de l’organisation et de l’utilisateur.
Choix MultiSelectPicklistAttributeMetadata	OptionSetValueCollection	Lorsqu’une seule option est sélectionnée, l’étiquette localisée de l’option sélectionnée. Lorsque plusieurs options sont sélectionnées, une chaîne avec les étiquettes localisées pour chaque option sélectionnée, séparées par `;` . Par exemple : `Appetizer; Entree; Dessert`
Option PicklistAttributeMetadata Statut StateAttributeMetadata Raison statut StatusAttributeMetadata	OptionSetValue	Étiquette localisée pour l’option sélectionnée.

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

Nom logique	Type
`primarycontactid`	EntityReference
`createdon`	DateTime
`revenue`	Money
`statecode`	OptionSetValue

static void FormattedValuesExample(IOrganizationService service)
{
    List<string> columns = new() {
        "name",
        "primarycontactid",
        "createdon",
        "revenue",
        "statecode"
    };

    QueryExpression query = new("account")
    {
        ColumnSet = new ColumnSet(columns.ToArray()),
        TopCount = 3
    };

    EntityCollection accounts = service.RetrieveMultiple(query);

    accounts.Entities.ToList().ForEach(x =>
    {
        string name = (string)x.Attributes["name"];
        string primarycontactid = x.Contains("primarycontactid") ? 
           x.FormattedValues["primarycontactid"] : 
           string.Empty;
        string createdon = x.FormattedValues["createdon"];
        string revenue = x.Contains("revenue") ? 
           x.FormattedValues["revenue"] : 
           string.Empty;
        string statecode = x.FormattedValues["statecode"];

        Console.WriteLine(@$"
name:{name}
    primary contact: {primarycontactid}
    created on: {createdon}
    revenue: {revenue}
    status: {statecode}"
            );
    });
}

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

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

name:City Power & Light (sample)
  primary contact: Scott Konersmann (sample)
  created on: 2/28/2024 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

Les colonnes qui utilisent un alias renvoient une AliasedValue

Lorsque vous récupérez des valeurs agrégées, vous devez spécifier un nom pour la colonne qui contient la valeur agrégée. Vous pouvez également spécifier des noms de colonnes différents pour les requêtes "normales", bien que cela soit moins courant.

Lorsque vous spécifiez un alias, la valeur renvoyée est enveloppée dans un AliasedValue. Le AliasedValue la classe a trois propriétés :

Property	Type	Description
`EntityLogicalName`	`String`	Nom logique de la table contenant la colonne d’où proviennent les données.
`AttributeLogicalName`	`String`	Nom logique de la colonne d’où proviennent les données.
`Value`	`Object`	La valeur agrégée ou la valeur de la ligne de la colonne à l’aide d’un alias.

Lorsque vous utilisez un alias de colonne, vous devez convertir le Value propriété pour accéder à la valeur renvoyée.

En savoir plus sur les alias de colonne :

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.

Notes

Il existe certaines fonctionnalités FetchXml que QueryExpression ne possède pas. Lors de la conversion d’une requête FetchXml en QueryExpression, ces différences sont perdues. En savoir plus sur les limitations de QueryExpression

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 : Number of conditions in query exceeded maximum limit..

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.

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

Lorsque vous comparez des valeurs de chaîne, ne vous inquiétez pas de la casse. Ce qui suit QueryExpression la requête renverra les enregistrements de compte avec le nom Contoso, Ltd et CONTOSO, LTD.

QueryExpression query = new("account")
{
   ColumnSet = new ColumnSet("name"),
   Criteria = new FilterExpression(LogicalOperator.And) { 
      Conditions = {
         { 
               new ConditionExpression(
                  attributeName: "name", 
                  conditionOperator: ConditionOperator.Equal, 
                  value: "CONTOSO, LTD") 
         }
      }
   },
   TopCount = 3
};