Opérations de classe d’entité utilisant le SDK pour .NET

  • Article

Lorsque vous travaillez avec les données Microsoft Dataverse à l’aide du SDK pour .NET, vous allez utiliser la classe Entity avec le style de liaison anticipée ou avec les classes d’entité générées à l’aide du style de liaison anticipée. Les classes d’entité générées proviennent de la classe Entity. Aussi comprendre la classe Entity est important pour chaque style.

Cette rubrique décrit certaines des propriétés et méthodes de la classe Entity utilisées le plus fréquemment.

Entity.LogicalName

Lorsque vous instanciez une nouvelle instance de classe Entity utilisant le style à liaison tardive, vous devez fournir une valeur de chaîne valide pour spécifier de quel type d’entité il s’agit. Le LogicalName est défini dans les métadonnées de l’entité (définition de la table).

Lors de l’utilisation du style de liaison anticipée, cette valeur est définie par le constructeur de la classe générée. Par exemple : var account = new Entity("account");

Dans votre code, si vous souhaitez récupérer ultérieurement la valeur de chaîne qui décrit le type d’entité, vous pouvez utiliser la propriété LogicalName. Cela est utile pour les nombreux API qui exigent un nom logique d’entité comme paramètre.

Entity.Id

Lorsque vous instanciez la classe Entity, que ce soit en utilisant le style à liaison tardive ou à liaison anticipée, elle n’a pas d’identifiant unique défini. Si vous créez une entité, vous ne devez pas la définir, mais la laisser être définie par le système lors de sa création (son enregistrement).

Si vous récupérez une entité, elle inclut la valeur d’attribut de clé primaire, que vous l’ayez demandée ou non. Le nom d’attribut de la clé primaire est différent de chaque type d’entité. En général, le nom de l’attribut de clé primaire est l’entité logicalname + id. Pour un compte c’est accountid et pour un contact c’est contactid.

Même si vous pouvez obtenir ou définir la valeur de clé primaire à l’aide de l’attribut de clé primaire, vous pouvez également utiliser la propriété Id pour accéder à la valeur sans avoir à vous rappeler du nom de l’attribut de clé primaire.

Accès à liaison anticipée aux colonnes de table

Si vous utilisez le style de liaison anticipée par rapport aux classes générées, vous trouvez les propriétés saisies pour chaque attribut dans la classe. Les propriétés pour les attributs utilisent la méthode AttributeMetadata.SchemaName et elles sont accessibles directement sur l’instance de classe Entity.

Par exemple :

//Using the early-bound Account entity class
var account = new Account();
// set attribute values
// string primary name
account.Name = "Contoso";
// Boolean (Two option)
account.CreditOnHold = false;
// DateTime
account.LastOnHoldTime = new DateTime(2017, 1, 1);
// Double
account.Address1_Latitude = 47.642311;
account.Address1_Longitude = -122.136841;
// Int
account.NumberOfEmployees = 500;
// Money
account.Revenue = new Money(new decimal(5000000.00));
// Picklist (Option set)
account.AccountCategoryCode = new OptionSetValue(1); //Preferred customer

Accès à liaison tardive aux colonnes de table

Les données contenues au sein d’une entité figurent dans la propriété Entity.Attributes . Cette propriété est une AttributeCollection qui offre un ensemble de méthodes pour ajouter de nouveaux attributs, vérifier si un attribut existe ou supprimer des attributs.

Découvrir les noms de colonnes et les types de données

Dans le style de liaison tardive, vous devez connaître la méthode AttributeMetadata.LogicalName pour l’attribut et le type de données. Le LogicalName est la version minuscule de SchemaName. Vous pouvez découvrir le LogicalName et saisir des attributs de plusieurs façons :

Les types d’attribut peuvent être les suivants. Cette liste n’est pas exhaustive.

Type Description
EntityReference Un attribut de recherche. Une liaison vers un autre enregistrement d’entité.
BooleanManagedProperty Utilisé uniquement pour les entités qui peuvent être des composants de solution, comme WebResource. Informations complémentaires : Utiliser des propriétés gérées
Money Un attribut Devise.
OptionSetValue Un attribut Groupe d’options. Les attributs État et Statut utilisent également ce type.
Boolean Un attribut à deux options.
Byte[] Un attribut d’image. Chaque entité peut comporter une image et l’attribut est intitulé entityimage. Une URL pour télécharger l’image peut être récupérée dans un attribut complémentaire intitulé entityimage_url. Pour plus d’informations : Attributs d’image
DateTime Un attribut Date et heure utilise généralement une valeur UTC. Pour plus d’informations : Comportement et format de l’attribut de date et d’heure
Decimal Un attribut Nombre décimal.
Double Un attribut Nombre à virgule flottante.
Guid Utilisé généralement en tant qu’identifiant unique pour l’entité.
Int32 Un attribut Nombre entier.
String Les attributs Plusieurs lignes de texte et Une seule ligne de texte utilisent ce type. Un autre type moins courant qui utilise une chaîne est les colonnes EntityName, qui stockent une valeur de chaîne représentant le nom logique d’une table.

Notes

Les colonnes de fichier ne sont pas disponibles directement à partir de l’entité. Vous devez utiliser une série de requêtes pour charger ou télécharger des données à partir de colonnes de fichiers. Plus d’informations : Utiliser les données de colonne de fichier.

Trois méthodes différentes existent pour interagir avec les attributs d’entité en utilisant le style de liaison tardive :

  • Utiliser l’indexeur sur la classe Entity
  • Utiliser l’indexeur sur la collection Attributes
  • Utilisez les méthodes Entity fournies

Utiliser l’indexeur sur la classe Entity

Dans la plupart des cas avec le style de liaison tardive, vous pouvez interagir avec la collection à l’aide de l’indexeur pour obtenir ou définir la valeur d’un attribut à l’aide du LogicalName de l’attribut. Par exemple, pour définir l’attribut de nom d’un compte :

//Use Entity class with entity logical name
var account = new Entity("account");
// set attribute values
// string primary name
account["name"] = "Contoso";
// Boolean (Two option)
account["creditonhold"] = false;
// DateTime
account["lastonholdtime"] = new DateTime(2017, 1, 1);
// Double
account["address1_latitude"] = 47.642311;
account["address1_longitude"] = -122.136841;
// Int
account["numberofemployees"] = 500;
// Money
account["revenue"] = new Money(new decimal(5000000.00));
// Picklist (Option set)
account["accountcategorycode"] = new OptionSetValue(1); //Preferred customer

Utiliser l’indexeur sur la collection Attributs

Comme vous le feriez sur l’entité, vous pouvez également accéder à une valeur à l’aide de l’indexeur sur la collection Attributs.

string accountName = account.Attributes["name"];

Utiliser les méthodes Entity

Vous pouvez également utiliser les méthodes Entity pour obtenir et définir les valeurs d’attribut.

Méthode Description
GetAttributeValue<T>(String) Utilisez celle-ci pour renvoyer une valeur d’attribut saisie
SetAttributeValue(String, Object) Utilisez celle-ci pour définir une valeur d’attribut saisie

Par exemple :

account.SetAttributeValue("name", "Account Name");
var accountName = account.GetAttributeValue<string>("name");

Entity.FormattedValues

Une valeur d’attribut d’entité qui peut être affichée dans l’interface utilisateur et n’est pas une chaîne a une valeur de chaîne formatée qui peut être utilisée pour afficher la valeur dans l’interface utilisateur. Par exemple :

  • Les valeurs monétaires ont une valeur de chaîne avec la devise et le formatage de précision appropriés.
  • Les valeurs de date ont un jeu de mise en forme dépendant de la manière dont le système est configuré.
  • Les valeurs OptionSet (choix) afficheront l’étiquette localisée qui représente la valeur entière

Notes

Les valeurs formatées s’appliquent uniquement aux entités qui ont été récupérées. Une fois que vous définissez la valeur, une nouvelle valeur formatée n’est pas calculée tant que vous n’avez pas enregistré l’entité et récupéré cette dernière à nouveau. La valeur formatée est générée sur le serveur.

Vous pouvez accéder aux valeurs mises en forme à l’aide de la collection FormattedValues utilisant un indexeur ou avec la méthode GetFormattedAttributeValue(String) de l’entité.

Par exemple, chacune d’elles récupère la même valeur mise en forme :

var formattedRevenueString1 = account.FormattedValues["revenue"];
var formattedRevenueString2 = account.GetFormattedAttributeValue("revenue");

Pour plus d’informations : Accéder aux valeurs formatées

Entity.RelatedEntities

Lorsque vous créez un enregistrement d’entité (ligne de table), vous pouvez également définir un ensemble d’enregistrements d’entité associés à créer dans la même opération. Plus d’informations : Créer des lignes de tables associées en une seule opération

Lorsque vous récupérez un enregistrement d’entité à l’aide de RetrieveRequest, vous pouvez définir RelatedEntitiesQuery avec une requête pour inclure les enregistrements d’entités associés dans les résultats. Pour plus d’informations : Extraire avec des lignes associées.

Si vous incluez des enregistrements d’entité associés dans les résultats, vous pouvez également mettre à jour les valeurs de ces enregistrements liés et les inclure lorsque vous mettez à jour l’enregistrement d’entité. Pour plus d’informations : Mettre à jour des lignes de tables associées en une seule opération

Convertir en une EntityReference

De nombreuses propriétés de messages nécessitent uniquement une EntityReference. Utilisez la méthode Entity.ToEntityReference() pour convertir un enregistrement d’entité en référence d’entité.

Convertir en une classe Entity

Si vous utilisez le style de liaison anticipée, vous devez convertir l’instance Entity en le type de classe d’entité générée que vous utilisez. Cela peut être généralement effectué avec un cast, mais vous pouvez également utiliser la méthode Entity.ToEntity<T>() .

Account account1 = (Account)retrievedEntity;
Account account2 = retrievedEntity.ToEntity<Account>();

Notes

Cette méthode ne peut pas être utilisée pour convertir une instance de classe Entity générée en une autre classe générée ou en Entity. Elle peut être utilisée uniquement pour convertir une instance Entity vers une des classes générées qui en proviennent. Si l’instance Entity n’est réellement pas une instance de la classe générée, ce message génère une erreur.

Étapes suivantes

Ces rubriques vous expliqueront plus en détail comment utiliser les entités Dataverse (lignes de table).

Démarrage rapide : exemple de SDK pour .NET (C#)
Rechercher des données
Créer des lignes de table
Récupérer une ligne de table
Mettre à jour et supprimer une ligne de table
Associer et dissocier des lignes de table
Générer des classes de programmation à liaison anticipée

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é).