Use an alternate key to create a record

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

Note

You can also update records using alternate keys. More information: Update with Alternate Key

Using alternate keys to create a table

You can create an Entity with a primary ID, a single KeyAttribute, or a collection of key columns in a single call using these constructors.

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 table and one of the following:

  • A value for ID (primary key GUID value)
  • A specified key value pair
  • A KeyAttributeCollection with a valid set of columns matching a defined key for the table.

Using alternate keys to create an EntityReference

You can also create an EntityReference with a primary ID, a single KeyAttribute, or a collection of key columns in a single call using these constructors.

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 table and either:

  • A value for ID (primary key GUID value)
  • A specified key value pair
  • A KeyAttributeCollection collection with a valid set of columns matching a defined key for the table.

Alternative input to messages

When passing tables to CreateRequest and UpdateRequest, values provided for lookup columns 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 table 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 column that is the primary key of the table and the value is valid, it populates the ID property of the Entity or EntityReference with the provided value.

  • If the key columns are provided, the system attempts to match the set of columns 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 columns. 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 a column set that is not defined as a unique key, an error will be thrown indicating that use of unique key columns is required.

See also

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