Use an alternate key to create a record

Applies To: Dynamics CRM 2015

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.

In This Topic

Using alternate keys to create an entity

Using alternate keys to create an EntityReference

Alternative input to messages

Exceptions when using alternate keys

Using alternate keys to create 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.

Using alternate keys to create an EntityReference

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.

Alternative input to messages

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.

Exceptions when using alternate keys

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.

See Also

Define alternate keys for an entity
Use change tracking to synchronize data with external systems
Use Upsert to insert or update a record

© 2016 Microsoft. All rights reserved. Copyright