Retrieve Record using Alternate Keys

Instead of retrieve a single record using

Entity IOrganizationService.Retrieve(string entityName, Guid id, ColumnSet columnSet);

You can easily retrieve the record using its alternate keys if you don’t have the id in advance:

var keys = new KeyAttributeCollection
	{ "new_parent", parentRef.Id },
	{ "new_code", "code01" }

var request = new RetrieveRequest
	ColumnSet = new ColumnSet("field_logical_name"),
	Target = new EntityReference("entity_logical_name", keys)

	var response = (RetrieveResponse)service.Execute(request);
	if (response.Entity != null)
		service.Delete(response.Entity.LogicalName, response.Entity.Id);
catch (Exception)

Note that if there is no record matched the keys, an exception will be thrown, you’ll need to handle the exception in that case.


Field Restriction in Alternate Keys

Alternate keys is a useful functionality introduced from CRM 2016. It allows you specify one or more fields to be an alternate key and use it to identify a record instead of using GUID. This is extremely helpful when you work with data migration and/or data integration between systems. More about Altenate Keys here.

Only attributes of the following types can be included in alternate key definitions: Decimal, Whole Number, Single line of text.

However, there are some restrictions in what field can be selected as alternate keys which the document doesn’t mention. Below is the non-exhausted list of them, I’ll update this if I find more:

  • Secured fields. A field with “Field Security” enabled doesn’t show up in the list when you creating alternate key.
  • “fullname” in “contact” entity
  • “domainname” in “systemuser” entity

So be aware when you work with alternate keys. Hope it helps!