Utilisation d’une clé secondaire pour créer un enregistrement

Article
03/22/2023

Vous pouvez désormais utiliser des clés secondaires pour créer des instances des classes Entity et EntityReference. Cette rubrique aborde les modèles d’utilisation et les exceptions possibles pouvant être renvoyées lorsque des clés secondaires sont utilisées. Pour comprendre comment définir des clés secondaires pour une entité, voir Définition de clés secondaires pour une entité.

Utilisation de clés secondaires pour créer une entité

Vous pouvez désormais créer une Entity avec un ID principal ou avec un KeyAttribute unique en un seul appel à l’aide du nouveau constructeur.

public Entity (string logicalName, Guid id) {…}    
public Entity (string logicalName, string keyName, object keyValue) {…}  
public Entity (string logicalName, KeyAttributeCollection keyAttributes) {…}

Une Entity valide utilisée pour les opérations de mise à jour contient un nom logique de l’entité et l’un des éléments suivants :

une valeur pour l’ID (valeur GUID de clé primaire) (ou)
un KeyAttributeCollection avec un ensemble d’attributs valide correspondant à une clé définie pour l’entité.

Utilisation de clés secondaires pour créer une EntityReference

Vous pouvez également créer une EntityReference sans ID principal et avec un KeyAttribute unique en un seul appel à l’aide du nouveau constructeur.

public EntityReference(string logicalName, Guid id) {…}    
public EntityReference(string logicalName, string keyName, object keyValue) {…}    
public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}

Un EntityReference valide comprend un nom logique de l’entité et soit :

une valeur pour l’ID (valeur GUID de clé primaire) ou
une collection KeyAttributeCollection avec un ensemble d’attributs valide correspondant à une clé définie pour l’entité.

Autre entrée pour les messages

En passant des entités vers CreateRequest et UpdateRequest, les valeurs données aux attributs de recherche utilisant EntityReference peuvent désormais utiliser EntityReference avec des clés secondaires définies dans KeyAttributes pour spécifier l’enregistrement associé. Elles seront résolues et remplacées par les références principales des entité basées sur les ID avant que les messages soient gérés.

Exceptions lors de l’utilisation de clés secondaires

Vous devez tenir compte des conditions et des exceptions possibles suivantes lorsque vous utilisez des clés secondaires :

L’ID principal est utilisé, s’il est fourni. S’il n’est pas fourni, KeyAttributeCollection est examinée. Si KeyAttributeCollection n’est pas fourni, une erreur est générée.
Si la KeyAttributeCollection fournie comprend un attribut qui est la clé primaire de l’entité et si la valeur est valide, il remplit la propriété ID de Entity ou de EntityReference avec la valeur fournie.
Si les attributs de clé sont fournis, le système tente de faire correspondre l’ensemble des attributs fournis avec les clés définies pour Entity. Si aucune correspondance n’est trouvée, une erreur est générée. Si une correspondance est trouvée, les valeurs fournies pour ces attributs sont validées. S’il est valide, il récupère l’ID de l’enregistrement correspondant aux valeurs de clé fournies, et remplit la valeur d’ID de Entity ou de EntityReference avec cette valeur.
Si vous spécifiez un attribut défini qui n’est pas défini comme clé unique, une erreur est générée, indiquant qu’il est nécessaire d’utiliser des attributs principaux uniques.

Voir aussi

Définition de clés secondaires pour une entité
Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes
Utilisation de Upsert pour insérer ou mettre à jour un enregistrement

Partager via