Data Access has been discontinued. Please refer to this page for more information.

What is an ObjectKey?

Each persistent type defined in your model has to have an identity that is made up of one ore more primitive members. Together these members uniquely identify an instance of the persistent type. During runtime you see this represented as an ObjectKey. An ObjectKey instance describes the identity of a persistent type. The ObjectKey plays a critical role in the life cycle of an entity, enabling your application to keep track of an entity, perform database updates, and more. Normally, this in-memory identifier is mapped directly to a primary key column(s) in the database.

In case the ObjectKey is not defined, you could set it in the mapping configuration of the persistent class with the help of the IsIdentity() method.

configuration.HasProperty(x => x.CategoryID).IsIdentity().
    HasFieldName("_categoryID").WithDataAccessKind(DataAccessKind.ReadWrite).
    ToColumn("CategoryID").IsNotNullable().HasColumnType("int").
    HasPrecision(0).HasScale(0);
configuration.HasProperty(Function(x) x.CategoryID).IsIdentity().
    HasFieldName("_categoryID").WithDataAccessKind(DataAccessKind.ReadWrite).
    ToColumn("CategoryID").IsNotNullable().HasColumnType("int").
    HasPrecision(0).HasScale(0)

The OpenAccessContext reads the ObjectKey information to perform many of its functions. If your model contains an entity without specified key (identity), then you will receive an exception each time you try to perform create, insert, update, delete operations with the context. The exception message should be similar to: "Invalid object name 'voa_keygen'. Telerik.OpenAccess.RT.sql.SQLException: Invalid object name 'voa_keygen'." In this case you should find all entities without keys in your model, and set any non-nullable primitive property as an Identity.

There are several requirements about the object key:

  • It must a non-nullable primitive property.
  • The type identity field must be System.Byte, System.Int16, System.Int32, System.Int64, System.Guid, System.Char or System.String.

An ObjectKey instance contains the persistent type name, and the entity's identity information, which could be from a single property, or could be a composite key that depends on a number of the entity's properties. The figure below shows an ObjectKey for the SingleIdentity object. It says the type name of this entity, and that its key property is composed of only one property, Id, whose value is 1.

An ObjectKey provides an array of key-value pairs - one for each identity member of the persistent type. The Key is the property name of the identity and the Value is its value. Each key-value pair is wrapped into an ObjectKeyMember instance.

ObjectKey with Version Information

An ObjectKey can optionally hold version information for a persistent object. An ObjectKey with version information identifies a persistent object with a specific version. Similar to the identity information, the version information in an ObjectKey consists of an array of key/value pairs - one for each field that participates in optimistic concurrency checks. Each key/value is represented by an ObjectVersionMember instance. Depending on the optimistic concurrency control mechanism used by a persistent type, one or more fields participate during optimistic concurrency checks.

For the ConcurrencyMode.Changed mode, the version information consists of all fields of the type that participate in concurrency checks since the values of all fields constitute a specific version of the instance. If a persistent type has its ConcurrencyMode property set to None, i.e. no concurrency checks will be performed during an update, then the ObjectKey for an instance of this type will have no version information.

You should not specify the version information for an ObjectKey explicitly in the code. You should use the ObjectKey.CreateWithVersion static method or the OpenAccessContext.CreateObjectKeyWithVersion method to obtain an ObjectKey with version.

In this section