Working with Entity Keys (Entity Framework)

Each entity type must have a key that is based on one or more scalar properties of the entity. Keys are defined by the Key element in the Entity Data Model (EDM). As in relational databases, these key values are used to verify the uniqueness of a given entity and to improve the performance of queries. Usually, key properties are mapped to a key column in the underlying table, either an identity column or some other column that is constrained to guarantee a unique value. For more information about how keys are defined in the EDM, see Key Attribute (EntityType CSDL).

When an object is returned by an object query, Object Services materializes the entity object. It also materializes the entity key into an instance of the EntityKey class. You can access this EntityKey from the EntityKey property of an object that implements IEntityWithKey. EntityObject, which is the base class for all data classes generated by the Entity Data Model tools, also implements IEntityWithKey.

Constructing and Using an EntityKey Object

An EntityKey object is composed of properties that define the entity and an array of one or more key/value pairs. A key/value pair consists of a property name and property value. When you create an EntityKey object, you must set the EntitySetName and EntityContainerName properties. You supply key/value pairs as one or more EntityKeyMember objects in the EntityKeyValues property.

You can also use the CreateEntityKey method on ObjectContext to get the EntityKey for a detached object. If the object does not have a valid key, the object context constructs a new EntityKey instance for the specified object. For more information, see How to: Create an EntityKey (Entity Framework).

Because an entity key uniquely identifies an entity, the key can be used to attach an object to an object context, even if the remaining object values were not retrieved from the data source. For more information, see How to: Attach Related Objects (Entity Framework). An entity key can also be used to retrieve an object from either the object context or from the data source. For more information, see How to: Return a Specific Object Using its Key (Entity Framework).

Entity Keys and Added Objects

The StoreGeneratedPattern attribute of the Property element of an entity in the relational model indicates that the property value is generated by the data source. When a value of StoreGeneratedPattern="identity" is set, Object Services replaces the value of the property in a temporary key with the identity value generated by the data source. When the Entity Data Model tools are used to generate a data model from an existing data source, the StoreGeneratedPattern attribute is added to each Property element that represents an identity or a computed column in the data source. For more information, see Store Generated Pattern (SSDL).

When a new entity object is created, a temporary key is defined and the IsTemporary property is set to true. When SaveChanges is called, a permanent key is assigned and the IsTemporary property is set to false. The following details the internal process that is used to replace the temporary key with a permanent key that contains the server-generated values:

1. The entity object is constructed.

   At this point the key properties all have default values, either null or 0.

2. The new object is added to the ObjectContext either by calling AddObject or one of the entity set-specific add methods in the context or by calling Add on a navigation property that returns an EntityCollection.

   At this point, Object Services generates a temporary key, which is used to store the objects in the ObjectStateManager.

3. SaveChanges is called on the ObjectContext.

   An INSERT statement is generated by Entity Services and is executed on the data source.

4. If the INSERT operation succeeds, server-generated values are written back to the ObjectStateEntry.

5. The ObjectStateEntry updates the object with the server-generated value.

6. When AcceptChanges is called on the ObjectStateEntry, a permanent EntityKey is computed using the new server-generated values.

   Note

   AcceptChanges is called automatically after SaveChanges, unless you specifically call the SaveChanges overload and pass a value of false for acceptChangesDuringSave.

7. The ObjectStateManager replaces all instances of the temporary key with the new permanent key.

GUID Property Values

The Entity Framework supports entity properties that return a Guid type. GUIDs are used to ensure uniqueness and GUID properties can be used as part of an entity key.

The Entity Framework does not support server-generated GUID values for primary key columns. This is because not all data sources support this behavior. When you use a GUID property as part of an entity key, you should always generate GUID values for new objects on the client application. To do this, we recommend handling the SavingChanges event to generate a new GUID value for any entity object in the Added state. For more information, see How to: Execute Business Logic When Saving Changes (Entity Framework). When you generate or update a data model with the Entity Data Model Wizard or the Update Model Wizard, GUID properties of entity types are automatically generated for uniqueidentifier-typed columns in the data source. A data source may also use 16-byte binary columns to store GUID values. Because the tools generate a binary property for each binary column in the data source, you must manually update the mapping of such columns to GUID properties by editing the .edmx file. For more information, see How to: Map a GUID Property to a Binary Column.

See Also

Tasks

How to: Create an EntityKey (Entity Framework)

Other Resources

Entity Data Model Tools