Interroger les données à l’aide du SDK pour .NET
Le SDK pour .NET fournit plusieurs méthodes pour interroger les données. Chacune présente différents avantages.
Method | Avantages |
---|---|
FetchExpression | Utilisez le langage de requête propriétaire FetchXML pour créer des requêtes complexes qui renvoient des agrégats tels que la somme d’une valeur pour tous les enregistrements renvoyés. Vous pouvez également effectuer des opérations de regroupement par 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 de FetchXML à l’exception des agrégats et du regroupement. 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 :
- 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é Query de la classe RetrieveMultipleRequest et utiliser la méthode IOrganizationService.Execute .
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 :
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);
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 :
- Interroger des données à l’aide de FetchXml
- À propos des requêtes de recherche rapide
- Paginer des résultats à l’aide de FetchXml
- Agréger des données à l’aide de FetchXml
- Exemple : Utiliser l’agrégation dans FetchXML
- Exemple : Utilisation FetchXML avec un cookie de pagination
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 :
- Générer des requêtes avec QueryExpression
- Mettre en page d’importants ensembles de résultats avec QueryExpression
- Utiliser la classe QueryExpression
- Utiliser la classe ConditionExpression
- Utiliser la classe ColumnSet
- Utiliser la classe FilterExpression
- Exemple : récupération multiple avec la classe QueryExpression
- Exemple : Utiliser QueryExpression avec un cookie de pagination
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é).
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : pendant toute l’année 2024, nous allons éliminer progressivement Problèmes GitHub comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, voir :Soumettre et afficher des commentaires pour