How to Check for Entity Changes

• The Session tracks all changes made to all entities that it has either loaded, stored, deleted, or queried for,
  and persists to the server only what is needed when SaveChanges() is called.

• This article describes how to check for changes made to a specific entity within a session.
  To check for changes to all tracked entities, see Check for session changes.

• To get the list of all entities tracked by the session, see Get tracked entities.

• In this page:

  • Check for entity changes
  • Get entity changes
  • Syntax

Check for entity changes

• The session's advanced property HasChanged indicates whether the specified entity was added, modified, or deleted within the session.

• Note: The HasChanged property is cleared after calling SaveChanges().

using (var session = store.OpenSession())
{
  // Store a new entity within the session
  // =====================================
  
  Employee employee = new Employee {FirstName = "John", LastName = "Doe"};
  session.Store(employee, "employees/1-A");
  
  // 'HasChanged' will be TRUE 
  Assert.True(session.Advanced.HasChanged(employee));
  
  // 'HasChanged' will reset to FALSE after saving changes 
  session.SaveChanges();
  Assert.False(session.Advanced.HasChanged(employee));
  
  // Load & modify entity within the session
  // =======================================
  
  employee = session.Load<Employee>("employees/1-A");
  Assert.False(session.Advanced.HasChanged(employee)); // FALSE
  
  employee.LastName = "Brown";
  Assert.True(session.Advanced.HasChanged(employee)); // TRUE
  
  session.SaveChanges();
  Assert.False(session.Advanced.HasChanged(employee)); // FALSE
}

Get entity changes

• Use the session's advanced method WhatChangedFor() to get all changes made to the specified entity
  within the session.

• Details will include:

  • The name and path of the changed field
  • Its old and new values
  • The type of change

• Note: WhatChangedFor() reports changes made prior to calling SaveChanges().
  Calling it immediately after SaveChanges will return no results, since all changes are cleared at that point.

Example I

using (var session = store.OpenSession())
{
  // Store (add) a new entity, it will be tracked by the session
  Employee employee = new Employee {FirstName = "John", LastName = "Doe"};
  session.Store(employee, "employees/1-A");

  // Get the changes for the entity in the session
  // Call 'WhatChangedFor', pass the entity object in the param
  DocumentsChanges[] changesForEmployee = session.Advanced.WhatChangedFor(employee);
  Assert.Equal(changesForEmployee.Length, 1); // a single change for this entity (adding)
  
  // Get the change type
  DocumentsChanges.ChangeType changeType = changesForEmployee[0].Change;
  Assert.Equal(changeType, DocumentsChanges.ChangeType.DocumentAdded);
  
  session.SaveChanges();
}

Example II

using (var session = store.OpenSession())
{
  // Load the entity, it will be tracked by the session
  Employee employee = session.Load<Employee>("employees/1-A");
  
  // Modify the entity
  employee.FirstName = "Jim";
  employee.LastName = "Brown";
  
  // Get the changes for the entity in the session
  // Call 'WhatChangedFor', pass the entity object in the param
  DocumentsChanges[] changesForEmployee = session.Advanced.WhatChangedFor(employee);
 
  Assert.Equal(changesForEmployee[0].FieldName, "FirstName");                           // Field name
  Assert.Equal(changesForEmployee[0].FieldNewValue, "Jim");                             // New value
  Assert.Equal(changesForEmployee[0].Change, DocumentsChanges.ChangeType.FieldChanged); // Change type
  
  Assert.Equal(changesForEmployee[1].FieldName, "LastName");
  Assert.Equal(changesForEmployee[1].FieldNewValue, "Brown");
  Assert.Equal(changesForEmployee[1].Change, DocumentsChanges.ChangeType.FieldChanged);
  
  session.SaveChanges();
}

Syntax

// HasChanged
bool HasChanged(object entity);

// WhatChangedFor
DocumentsChanges[] WhatChangedFor(object entity);

Return value
DocumentsChanges[]	List of changes made to the entity

public class DocumentsChanges
{
  public object FieldOldValue { get; set; }  // Previous field value
  public object FieldNewValue { get; set; }  // Current field value
  public ChangeType Change { get; set; }     // Type of change that occurred
  public string FieldName { get; set; }      // Name of field on which the change occurred
  public string FieldPath { get; set; }      // Path of field on which the change occurred
  public string FieldFullName { get; }       // Path + Name of field on which the change occurred
}

public enum ChangeType
{
  DocumentDeleted,
  DocumentAdded,
  FieldChanged,
  NewField,
  RemovedField,
  ArrayValueChanged,
  ArrayValueAdded,
  ArrayValueRemoved
}