| title | description | author | ms.date | uid |
|---|---|---|---|---|
Keys - EF Core |
How to configure keys for entity types when using Entity Framework Core |
AndriySvyryd |
10/14/2022 |
core/modeling/keys |
A key serves as a unique identifier for each entity instance. Most entities in EF have a single key, which maps to the concept of a primary key in relational databases (for entities without keys, see Keyless entities). Entities can have additional keys beyond the primary key (see Alternate Keys for more information).
By convention, a property named Id or <type name>Id will be configured as the primary key of an entity.
[!code-csharpMain]
Note
Owned entity types use different rules to define keys.
You can configure a single property to be the primary key of an entity as follows:
[!code-csharpKeySingle]
[!code-csharpKeySingle]
You can also configure multiple properties to be the key of an entity - this is known as a composite key. Conventions will only set up a composite key in specific cases - like for an owned type collection.
Note
The [PrimaryKey] attribute was introduced in EF Core 7.0. Use the Fluent API in older versions.
[!code-csharpKeyComposite]
[!code-csharpKeyComposite]
For non-composite numeric and GUID primary keys, EF Core sets up value generation for you by convention. For example, a numeric primary key in SQL Server is automatically set up to be an IDENTITY column. For more information, see the documentation on value generation and guidance for specific inheritance mapping strategies.
By convention, on relational databases primary keys are created with the name PK_<type name>. You can configure the name of the primary key constraint as follows:
[!code-csharpMain]
While EF Core supports using properties of any primitive type as the primary key, including string, Guid, byte[] and others, not all databases support all types as keys. In some cases the key values can be converted to a supported type automatically, otherwise the conversion should be specified manually.
Key properties must always have a non-default value when adding a new entity to the context, but some types will be generated by the database. In that case EF will try to generate a temporary value when the entity is added for tracking purposes. After SaveChanges is called the temporary value will be replaced by the value generated by the database.
Important
If a key property has its value generated by the database and a non-default value is specified when an entity is added, then EF will assume that the entity already exists in the database and will try to update it instead of inserting a new one. To avoid this, turn off value generation or see how to specify explicit values for generated properties.
An alternate key serves as an alternate unique identifier for each entity instance in addition to the primary key; it can be used as the target of a relationship. When using a relational database this maps to the concept of a unique index/constraint on the alternate key column(s) and one or more foreign key constraints that reference the column(s).
Tip
If you just want to enforce uniqueness on a column, define a unique index rather than an alternate key (see Indexes). In EF, alternate keys are read-only and provide additional semantics over unique indexes because they can be used as the target of a foreign key.
Alternate keys are typically introduced for you when needed and you do not need to manually configure them. By convention, an alternate key is introduced for you when you identify a property which isn't the primary key as the target of a relationship.
[!code-csharpMain]
You can also configure a single property to be an alternate key:
[!code-csharpMain]
You can also configure multiple properties to be an alternate key (known as a composite alternate key):
[!code-csharpMain]
Finally, by convention, the index and constraint that are introduced for an alternate key will be named AK_<type name>_<property name> (for composite alternate keys <property name> becomes an underscore separated list of property names). You can configure the name of the alternate key's index and unique constraint:
[!code-csharpMain]