Use an alternate key to reference a record

When you use the Web API, you reference a specific record by using a URL. 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 by using the @odata.bind syntax, or as parameters to functions and actions.

The following table provides examples that show how to reference records by using relative URLs:

Exceptions when using alternate keys with the Web API

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 occurs. 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 can't include some special characters.

  Alternate key values with the following characters /,<,>,*,%,&,:,\\,?,+ aren't supported. These special characters are reserved or structurally significant in a URL path segment. Dataverse will return an error if you send a GET request with these values within the parentheses of the URL. The workaround is not to retrieve a single record, but to use the alternate key values with $filter to retrieve a collection that contains the one record that matches the alternate key values.

  For example, instead of this request that fails:

  GET [Organization URI]/api/data/v9.2/new_skts(new_name='M%26M')
  

  Use a $filter query:

  GET [Organization URI]/api/data/v9.2/new_skts?$filter=new_name eq 'M%26M'&$select=new_name
  

  If you only need to access the record, you can take the data from the first (and only) matching record in the value collection returned. If you need to perform some other action, like updating or deleting the record, you can use this approach to get the ID of the matching record and then refer to the record conventionally using the ID value rather than the value of alternate keys.

  Note

  Parameter aliases (@param) don't work with alternate key syntax. Using a parameter alias in a key predicate returns a 400 error even for values without special characters. Use $filter instead.

More information: Retrieve record using an alternate key

When you use the SDK for .NET, you can use alternate keys in two ways.

Using the Entity class

When you create an instance of the Entity class, specify the keys to identify the record by 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 constructors add values to the Entity.KeyAttributes property, not the Entity.Attributes property. Use KeyAttributes 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, specify the keys to identify the record by 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) {…}    

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

Exceptions when using alternate keys with the SDK for .NET

Be aware of the following conditions and possible exceptions when using alternate keys:

• The SDK uses the Entity.Id property if you provide it. If you don't provide it, the SDK examines the KeyAttributeCollection. If you don't provide the KeyAttributeCollection, the SDK throws an error.
• If the provided KeyAttributeCollection includes one column that is the primary key of the table and the value is valid, the SDK populates the Entity.Id property or EntityReference.Id Property with the provided value.
• If you provide key columns, the system attempts to match the set of columns you provide with the keys defined for the Entity. If it doesn't find a match, it throws an error. If it finds 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 populates the Entity.Id property or EntityReference.Id Property with this value.
• If you specify a column that isn't defined as a unique key, the SDK throws an error indicating that use of unique key columns is required.