Présentation des attributs d’entité

Les entités incluent un ensemble d’attributs qui représentent les données pouvant être incluses dans chaque enregistrement. Les développeurs doivent connaître les différents types d’attributs et savoir les utiliser. Les métadonnées des attributs décrivent les opérations et les comportements valides des différents types d’attributs. Plusieurs types d’attributs peuvent être regroupés par des comportement courants.

L’expérience spécifique des développeurs dépendra du style de leur développement. Plus d’informations : Programmation d’entité (liaison anticipée, liaison tardive et extensions développeur).

Note

Cette rubrique inclut des références à plusieurs propriétés des métadonnées. Pour afficher les métadonnées d’entité pour votre organisation, installez la solution Navigateur de métadonnées décrite dans l’article Accès aux métadonnées de votre organisation. Vous pouvez également accéder à la documentation de référence pour les entités dans Référence d’entité.

Opérations valides sur les attributs

Chaque attribut possède des métadonnées qui décrivent les opérations qu’il prend en charge. Vous devez être connaître les opérations valides pour les attributs que vous utilisez.

Propriété AttributeMetadata	Description
IsValidForCreate	True si cet attribut est valide pour être défini lorsqu’un enregistrement est créé, sinon false.
IsValidForRead	True si la valeur de cet attribut peut être récupérée, sinon false.
IsValidForUpdate	True si cet attribut est valide pour être défini lorsqu’un enregistrement est mis à jour, sinon false.

Types d’attributs

Les attributs sont définis dans les métadonnées et la propriété AttributeMetadata .AttributeTypeName contient la valeur décrivant le type. Les membres AttributeTypeDisplayName statiques fournissent la liste des types possibles.

Note

La propriété AttributeType plus ancienne contient les données qui sont principalement alignées avec AttributeTypeName, sauf qu’elle affiche les attributs ImageType comme Virtual. Utilisez la propriété AttributeTypeName plutôt que la propriété AttributeType.

La section suivante regroupe les types d’attributs en catégories pour que vous puissiez les comparer plus facilement :

• Attributs de données de catégorisation

• Attributs de collection de données

• Attribut des données de date et heure.

• Attributs des données d’image

• Attributs de données de quantité

• Attributs des données de référence

• Attributs des données de chaîne

• Attributs de données d’identificateur unique

• Attributs virtuels

Attributs de données de catégorisation

Chacun des cinq attributs de ce groupe hérite d’une classe de base EnumAttributeMetadata commune et utilise un ensemble prédéfini de valeurs valides pour regrouper les enregistrements en catégories.

Définissez les attributs Picklist, Status et State à l’aide d’un OptionSetValue avec une propriété Value définie sur un entier qui représente une option valide au sein des métadonnées.

Définissez les attributs booléens avec une valeur booléenne, mais sachez qu’il s’agit d’une catégorisation limitée à deux options uniquement.

Les attributs EntityName utilisent une valeur de chaîne contrainte pour être un nom logique d’entité valide dans l’organisation.

Les attributs personnalisés Picklist et Boolean peuvent être définis comme attributs calculés. Pour plus d’informations : Attributs calculés.

Type de métadonnées	Valeur AttributeTypeName	Description
PicklistAttributeMetadata	PicklistType	Les valeurs sont définies dans OptionMetadata.Value pour cet attribut défini dans OptionSetMetadata.Options. Dans les outils de personnalisation de l’application, ces attributs sont appelés champs duGroupe d’options.
StatusAttributeMetadata	StatusType	Ces attributs système sont généralement nommés StatusCode. Les valeurs sont définies dans StatusOptionMetadata.Value pour cet attribut défini dans OptionSetMetadata.Options. La propriété StatusOptionMetadata.State de chaque option décrit la valeur valide pour la valeur StateCode correspondante. Avant de définir StatusCode , vous devez vérifier qu’il est valide pour la valeur StateCode actuelle. Utilisez le message SetStateRequest pour définir les valeurs d’attribut StatusCode et StateCode lorsque vous devez modifier le statut de l’enregistrement. Ces attributs peuvent avoir d’autres restrictions selon lesquelles les valeurs peuvent être définies. La propriété StatusOptionMetadata.TransitionData peut contenir des informations relatives aux options autorisées quand la valeur EntityMetadata. La valeur EnforceTransitions est définie sur true. En savoir plus : Définir les transitions de modèles d’état personnalisés.
StateAttributeMetadata	StateType	Ces attributs système sont généralement nommés StatusCode. Les valeurs sont définies dans StateOptionMetadata.Value pour cet attribut défini dans OptionSetMetadata.Options. StateCode n’est pas valide pour la mise à jour Une fois l’enregistrement créé, StateCode peut être défini avec le message SetStateRequest. La propriété StateOptionMetadata.DefaultStatus de chaque option décrit le StatusCode par défaut qui sera utilisé s’il n’est pas défini comme paramètre dans SetStateRequest.
BooleanAttributeMetadata	BooleanType	Les attributs booléens peuvent être définis directement avec une valeur booléenne, mais comme les autres ils ont aussi une propriété OptionSet avec les propriétés FalseOption et TrueOption correspondant aux options booléennes. Chacune de ces propriétés définit un ensemble d’étiquettes localisées représentant ce que les valeurs true et false signifient pour l’attribut. Dans les outils de personnalisation de l’application, ces attributs sont appelés champs Deux options, car la signification de chaque option peut être n’importe quelle paire d’options mutuellement exclusives, et pas simplement true et false. Par exemple, les options peuvent être « big » (grand) et « small » (petit).
EntityNameAttributeMetadata	EntityNameType	Ces attributs système sont généralement accouplés avec un attribut d’identificateur unique ou de référence valide pour plusieurs types. La valeur de cet attribut est une valeur de chaîne représentant le nom logique d’une entité. Si l’attribut de référence correspondant est EntityReference, la valeur de cet attribut est la même que la valeur de propriété EntityReference.Name.

Attributs de collection de données

Ces attributs système retournent des collections de valeurs.

Valeur AttributeTypeName	Description
CalendarRulesType	Aucun attribut réel n’utilise CalendarRulesType. Lorsque vous utilisez le style de liaisons anticipée, l’outil de génération de code crée les deux attributs simulés suivants, qui ne sont pas présents dans les métadonnées. Ces attributs représentent réellement une vue des enregistrements des règles du calendrier associée à une relation un-à-plusieurs à l’instance d’entité. - Relation Calendar.CalendarRules : calendar_calendar_rules - Relation Service.CalendarRules : service_calendar_rules
PartyListType	Les attributs suivants permettent de définir plusieurs EntityReference pour différents types d’activités. ActivityPointer.allparties Appointment.OptionalAttendees Appointment.Organizer Appointment.requiredattendees CampaignActivity.from CampaignActivity.Partners CampaignResponse.Customer CampaignResponse.from CampaignResponse.Partner Email.bcc Email.cc Email.from Email.to Fax.from Fax.to Letter.bcc Letter.cc Letter.from Letter.to PhoneCall.from PhoneCall.to RecurringAppointmentMaster.OptionalAttendees RecurringAppointmentMaster.Organizer RecurringAppointmentMaster.RequiredAttendees ServiceAppointment.Customers ServiceAppointment.Resources SocialActivity.From SocialActivity.Resources SocialActivity.To

Attribut des données de date et heure.

Attributs avec la valeur AttributeTypeName de métadonnées de DateTimeType. Définissez ces attributs avec System.DateTime.

La propriété DateTimeAttributeMetadata.Format peut être une des valeurs DateTimeFormat suivantes :

• DateAndTime : affiche la date et l’heure.

• DateOnly : affiche la date uniquement

  Les attributs personnalisés Date et Time peuvent être définis comme attributs calculés ou attributs de report. Pour plus d’informations : Attributs calculés et de report.

Attributs des données d’image

Pour les entités prenant en charge les attributs d’image, le SchemaName de l’attribut d’image de l’entité est toujours EntityImage.

En savoir plus : Attributs d’image, Images d’entité et Exemple : Définir et récupérer des images d’entité.

Attributs de données de quantité

Les attributs de cette catégorie utilisent des données numériques. Chacun de ces attributs possède une propriété de métadonnées MaxValue et MinValue pour définir une plage de valeurs valides.

Les attributs personnalisés Decimal, Integer et Money peuvent être définis comme attributs calculés ou attributs de report. Pour plus d’informations : Attributs calculés et de report.

Type de métadonnées	Valeur AttributeTypeName	Description
BigIntAttributeMetadata	BigIntType	Les attributs sont réservés à une utilisation interne uniquement.
DecimalAttributeMetadata	DecimalType	Utilisez les valeurs de type decimal. La propriété de métadonnées Precision définit la précision à utiliser pour l’attribut.
DoubleAttributeMetadata	DoubleType	Utilisez les valeurs de type double. La propriété de métadonnées Precision définit la précision à utiliser pour l’attribut.
IntegerAttributeMetadata	IntegerType	Utilisez les valeurs de type int (entier).
MoneyAttributeMetadata	MoneyType	Utilisez Money qui possède une propriété decimal``Value. Chaque attribut Money possède un attribut de devise monétaire de base calculé par le système correspondant et qui est utilisée pour calculer la valeur de la devise de base de l’organisation lorsque plusieurs devises ont été autorisées pour l’organisation. La propriété IsBaseCurrency identifie si l’attribut Money représente la devise de base. Pour plus d’informations : Entité Transaction Currency (devise). Les attributs Money ont également une propriété de métadonnées PrecisionSource qui peut spécifier le niveau de précision à utiliser. La valeur entière de cette propriété détermine si : - 0 : la précision est déterminée par la propriété des métadonnées Precision. - 1 : la valeur Organization.PricingDecimalPrecision. - 2 : la TransactionCurrency.CurrencyPrecision associée à l’enregistrement actif.

Attributs des données de référence

Ces attributs sont communément mentionnés comme attributs de recherche et chacun d’eux contient une valeur EntityReference. La différence entre ces attributs concerne les types d’entités auxquels ils peuvent s’associer. La propriété de métadonnées Targets contient un String[] contient des noms logiques d’entité valides représentant les cibles valides pour la recherche. Les attributs de recherche personnalisés peuvent avoir un seul type dans la propriété Targets.

Les PartyListType représentent également un type d’attribut de données de référence, mais comme ils contiennent un ensemble de références, ils sont inclus dans les Attributs de collection de données.

Type de métadonnées	Valeur AttributeTypeName	Description
LookupAttributeMetadata	CustomerType	Ces attributs de recherche système peuvent se lier aux enregistrements d’entité Account ou Contact. Contact.ParentCustomerId Contract.BillingCustomerId Contract.CustomerId ContractDetail.CustomerId CustomerOpportunityRole.CustomerId CustomerRelationship.CustomerId CustomerRelationship.PartnerId Entitlement.CustomerId Incident.CustomerId Invoice.CustomerId Lead.CustomerId Opportunity.CustomerId Quote.CustomerId SalesOrder.CustomerId SocialActivity.PostAuthor SocialActivity.PostAuthorAccount SocialProfile.CustomerId
LookupAttributeMetadata	LookupType	Ces attributs de recherche peuvent être utilisés pour définir des références à un enregistrement du type indiqué par la propriété de métadonnées Targets. Certaines recherches système n’ont pas de valeur définie pour la propriété Targets, mais l’entité attendue doit être visible en fonction de la relation d’entité associée à la recherche.
LookupAttributeMetadata	OwnerType	Ces recherches système sont toujours nommées OwnerId et chaque entité détenue par l’utilisateur en possède une. Elles peuvent faire référence à des enregistrements SystemUser ou Team.

Attributs des données de chaîne

Il existe deux types d’attributs qui utilisent les données de chaîne.

Type de métadonnées	Valeur AttributeTypeName	Description
StringAttributeMetadata	StringType	Un attribut pour une valeur de chaîne à laquelle une mise en forme peut être appliquée. Pour plus d’informations : Formats StringAttributeMetadata. Les attributs String personnalisés peuvent être définis comme attributs calculés. Pour plus d’informations : Attributs calculés.
MemoAttributeMetadata	MemoType	Un attribut pour une valeur de chaîne conçu pour les notes. Cet attribut est équivalent aux attributs String avec la valeur de propriété FormatName définie sur TextArea.

Attributs de données d’identificateur unique

Les attributs avec la valeur AttributeTypeName de métadonnées égale à UniqueidentifierType contiennent des valeurs Nullable System.Guid.

Chaque instance d’entité comprend un attribut qui représente l’identificateur unique de l’enregistrement. Cet attribut possède un nom de schéma qui suit la convention d’affectation de noms <nom de schéma de l’entité>+Id. Par exemple, le nom de schéma de l’entité Compte pour l’attribut représentant l’identificateur unique se nomme AccountId. Cette valeur est aussi directement accessible avec la propriété Entity.Id. Cet attribut est toujours renvoyé lorsque vous récupérez une entité, même si vous ne l’incluez pas dans le ColumnSet d’une requête. Cette valeur est null pour une entité nouvellement instanciée. Même si elle est valide pour spécifier une valeur GUID et définir l’identificateur unique lorsque vous créez un enregistrement, pour des raisons de performances, nous vous recommandons de la laisser comme null et d’autoriser le système à attribuer une valeur quand l’enregistrement est créé. Lorsqu’un enregistrement est enregistré, cette valeur devient en lecture seule.

Les entités peuvent inclure d’autres attributs d’identificateur unique, selon les fonctionnalités de l’entité. Par exemple, les entités activées pour les processus métier contiennent des attributs d’identificateur unique pour ProcessId et StageId afin de suivre le processus métier actif associé à l’enregistrement. Certaines relations système peuvent généralement utiliser une valeur d’EntityReference utilisent à la place un identificateur unique. Par exemple les entités Account et Contact ont chacune deux attributs d’identificateur unique (Address1_AddressId et Address2_AddressId) qui correspondent aux enregistrements CustomerAddress créés lorsqu’un compte ou un contact est créé.

Attributs virtuels

Les métadonnées d’une entité incluent certains attributs avec la valeur AttributeTypeName de métadonnées de VirtualType. Ces attributs ne peuvent pas être utilisés dans le code.

Attributs logiques

Les attributs logiques contiennent des valeurs stockées dans des tables de base de données différentes de celles des autres attributs de l’entité. Dans la plupart des cas, cette implémentation interne n’est d’aucune utilité dans l’utilisation de Dynamics 365 Customer Engagement (on-premises). Lorsque vous utilisez des attributs logiques comme source pour un champ calculé, les valeurs de ce champ calculé ne peuvent pas être triées. Utilisez la propriété AttributeMetadata.IsLogical pour détecter si un attribut est un attribut logique.

Les attributs logiques les plus courants sont ceux qui stockent les informations d’adresse dans plusieurs entités spéciales : CompetitorAddress, CustomerAddress, InternalAddress, LeadAddress et PublisherAddress. Il existe 8 entités système qui incluent un ensemble complet d’attributs pour les deux adresses utilisant des attributs logiques. Chacun de ces attributs commence par « Address* », comme Address1_City ou Address2_Latitude.

Voir aussi

Présentation des entités dans Dynamics 365 Customer Engagement (on-premises)
Attributs d’image
Attributs calculés et attributs de report
Exemple : Récupérer les transitions d’état valides
Exemple : Définir et récupérer des images d’entité