Use an alternate key to reference a record

When you use the Web API, you reference a specific record using a URL and then use the POST, PATCH, or DELETE Http methods to perform the data operation. You also use URLs to set values for single-valued navigation properties using the @odata.bind syntax, or as parameters to functions and actions.

The following table provides examples showing how to reference records using relative urls:

Exceptions when using alternate keys with the Web API

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

• If you specify a column that isn't defined as a unique key, an error is thrown indicating that use of unique key columns is required. The error message is: The key in the request URI is not valid for resource 'Microsoft.Dynamics.CRM.<table logical name>'. Ensure that the names and number of key properties match the declared or alternate key properties for the resource 'Microsoft.Dynamics.CRM.<table logical name>'.
• Alternate key values with the following characters /,<,>,*,%,&,:,\\,?,+ aren't currently supported.

More information: Retrieve record using an alternate key

When you use the SDK for .NET, there are two ways to use alternate keys.

Using the Entity class

When you create an instance of the Entity class you can specify the keys to use to identify the record using the following Entity Constructors:

// For use with the primary key
public Entity (string logicalName, Guid id) {…} 
// For use with a single alternate key value
public Entity (string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public Entity (string logicalName, KeyAttributeCollection keyAttributes) {…}  

These values are added to the Entity.KeyAttributes property, not the Entity.Attributes property. KeyAttributes are used to identify a record. Attributes contains the data for the record.

For example, when a table has an alternate key that includes two alternate key columns, you can define the entity this way.

KeyAttributeCollection keys = new KeyAttributeCollection() {
   { "example_key1", 5 },
   { "example_key2", 5 }
};

Entity thing = new Entity("example_thing", keys);
thing["example_name"] = "Test Name";

Using the EntityReference class

When you create an instance of the EntityReference class you can specify the keys to use to identify the record using the following EntityReference constructors that use the same pattern as the Entity class constructors.

// For use with the primary key
public EntityReference(string logicalName, Guid id) {…}
// For use with a single alternate key value
public EntityReference(string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}    

• You can use EntityReference to set values for entity lookup columns. When used to set a lookup column, the key values are used to find the primary key value, and the primary key values is stored in the database.
• You can use EntityReference for messages that use this type as a property, such as Delete using the DeleteRequest class.

Exceptions when using alternate keys with the SDK for .NET

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

• The Entity.Id property will be used if it's provided. If it isn't provided, it examines the KeyAttributeCollection. If the KeyAttributeCollection isn't provided, it throws 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 Entity.Id property or EntityReference.Id Property 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 doesn't find a match, it throws an error. If it does find a match, it validates the provided values for those columns. If valid, it retrieves the primary key value of the record that matched the provided alternate key values, and populate the Entity.Id property or EntityReference.Id Property with this value.
• If you specify a column that isn't defined as a unique key, an error is thrown indicating that use of unique key columns is required.