Use an alternate key to create a record

 

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You can now use alternate keys to create instances of Entity and EntityReference classes. This topic discusses the usage patterns and possible exceptions that might be thrown when using alternate keys. To understand how to define alternate keys for an entity, see Define alternate keys for an entity.

You can now create an Entity with a primary ID or with a single KeyAttribute in a single call using the new constructor.

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

A valid Entity used for update operations includes a logical name of the entity and one of the following:

  • A value for ID (primary key GUID value) (or)

  • A KeyAttributeCollection with a valid set of attributes matching a defined key for the entity.

You can also create an EntityReference without a primary ID, and with a single KeyAttribute in a single call using the new constructor.

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

A valid EntityReference includes a logical name of the entity and either:

  • A value for ID (primary key GUID value) or

  • A KeyAttributeCollection collection with a valid set of attributes matching a defined key for the entity.

When passing entities to CreateRequest and UpdateRequest, values provided for Lookup attributes using an EntityReference can now use EntityReference with alternate keys defined in KeyAttributes to specify related record.  These will be resolved to and replaced by primary ID based entity references before the messages are processed.

You have to be aware of the following conditions and possible exceptions when using alternate keys:

  • The primary ID is used if it is provided. If it is not provided, it will examine the KeyAttributeCollection. If the KeyAttributeCollection is not provided, it will throw an error.

  • If the provided KeyAttributeCollection includes one attribute that is the primary key of the entity and the value is valid, it populates the ID property of the Entity or EntityReference with the provided value.

  • If the key attributes are provided, the system attempts to match the set of attributes provided with the keys defined for the Entity. If it does not find a match, it will throw an error. If it does find a match, it will validate the provided values for those attributes. If valid, it will retrieve the ID of the record that matched the provided key values, and populate the ID value of the Entity or EntityReference with this value.

  • If you specify an attribute set that is not defined as a unique key, an error will be thrown indicating that use of unique key attributes is required.

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Show: