The original value is the value as it was retrieved from the database.

When existing data is loaded from a database, the record keeps track of the original value for each column. 

Only a record with record status Existing or ExistingDelete can have original value tracking enabled.

With a New record, original-value tracking is always disabled.

Once original value tracking is enabled for record, it will remain enabled for the lifetime of the record.

When a column property value in a original-value tracked record is modified this is what happens:

  • The current value is copied into the original value buffer;
  • The column is flagged as modified.

To test if original value tracking is enabled for a record, call the Record.StartedWithDbValues method. It returns true when original value tracking is enabled.

The purpose of original value tracking

Original value tracking allows for a more advanced administration of a column's modification flag.

Original value tracking disabled

A column is considered modified when its value is set.

Original value tracking enabled

A column is considered modified when its value does not match the original-value. When you change a column to a value different from the original value, the column is marked as modified. When you change that column back to the original value, the column reverts to not-modified.

Changing primary keys

Since the record registers both original and new primary key values, the SQL statement resulting from a SaveChanges call can modify primary key values in the database table:

UPDATE <new primary key value> WHERE <original primary key value>

Existing records without original value tracking

It is possible for an Existing record to have original value tracking disabled.

This happens when you reset the record status of a New record to an Existing record. Resetting is done by calling Record.ResetToExisting or Record.ResetToUnmodifiedExisting

For a New record there are no original values, and thus original value tracking remains disabled.

New values become original values

When original-value tracking is enabled, and you call Record.ResetToUnmodified or Record.ResetToUnmodifiedExisting on an Existing record, then the current values will be considered the original values. Just as if those values were freshly received from the database.

In other words: you are telling the record that "the values in the record match the values in the database"