Session: How to Disable Entity Tracking

Tracking can be turned off by setting the SessionOptions.NoTracking property to true. When turned off, the Store() and SaveChanges() methods will no longer be available (an exception will be thrown if they are used). Each call to one of the Load methods will create a new instance of the entity.

Example

using (IDocumentSession Session = store.OpenSession(new SessionOptions
{
    NoTracking = true
}))
{
    Employee employee1 = Session.Load<Employee>("employees/1-A");
    Employee employee2 = Session.Load<Employee>("employees/1-A");

    // because NoTracking is set to 'true'
    // each load will create a new Employee instance
    Assert.NotEqual(employee1, employee2);
}

using (IAsyncDocumentSession Session = store.OpenAsyncSession(new SessionOptions
{
    NoTracking = true
}))
{
    Employee employee1 = await Session.LoadAsync<Employee>("employees/1-A");
    Employee employee2 = await Session.LoadAsync<Employee>("employees/1-A");

    // because NoTracking is set to 'true'
    // each load will create a new Employee instance
    Assert.NotEqual(employee1, employee2);
}

In the Document Store conventions, you can configure the ShouldIgnoreEntityChanges method to fine-tune which entities to ignore and when. The function can take several parameters including a session and an entity, and returns a boolean. If the function returns true, changes tothe given entity will not be tracked. Changes to that entity will be ignored and will not be persisted on SaveChanges().

public Func<InMemoryDocumentSessionOperations, object, string, bool> ShouldIgnoreEntityChanges;

Example

In this example the ShouldIgnoreEntityChanges function returns true for any entity that is of type Employee and whose FirstName property is 'Bob'. An employee with the first name 'Bob' is not persisted, but as soon as their FirstName is changed to something else, their changes are tracked and will be persisted.

using (var store = new DocumentStore()
{
    Conventions =
    {
        ShouldIgnoreEntityChanges =
            (session, entity, id) => (entity is Employee e) &&
                                     (e.FirstName == "Bob")
    }
}.Initialize())
{
    using (IDocumentSession Session = store.OpenSession())
    {
        var employee1 = new Employee() { Id = "employees/1",
                                         FirstName = "Alice" };
        var employee2 = new Employee() { Id = "employees/2",
                                         FirstName = "Bob" };

        Session.Store(employee1); // Entity is tracked
        Session.Store(employee2); // Entity is ignored

        Session.SaveChanges(); // Only employee1 is persisted

        employee1.FirstName = "Bob"; // Entity is now ignored
        employee2.FirstName = "Alice"; // Entity is now tracked

        Session.SaveChanges(); // Only employee2 is persisted
    }
}