ChangeTracker Class

Definition

Provides access to change tracking information and operations for entity instances the context is tracking. Instances of this class are typically obtained from ChangeTracker and it is not designed to be directly constructed in your application code.

public class ChangeTracker : Microsoft.EntityFrameworkCore.Infrastructure.IInfrastructure<Microsoft.EntityFrameworkCore.ChangeTracking.Internal.IStateManager>
public class ChangeTracker : Microsoft.EntityFrameworkCore.Infrastructure.IInfrastructure<Microsoft.EntityFrameworkCore.ChangeTracking.Internal.IStateManager>, Microsoft.EntityFrameworkCore.Infrastructure.IResettableService
public class ChangeTracker : Microsoft.EntityFrameworkCore.Infrastructure.IResettableService
type ChangeTracker = class
    interface IInfrastructure<IStateManager>
type ChangeTracker = class
    interface IInfrastructure<IStateManager>
    interface IResettableService
type ChangeTracker = class
    interface IResettableService
Public Class ChangeTracker
Implements IInfrastructure(Of IStateManager)
Public Class ChangeTracker
Implements IInfrastructure(Of IStateManager), IResettableService
Public Class ChangeTracker
Implements IResettableService
Inheritance
ChangeTracker
Implements
IInfrastructure<Microsoft.EntityFrameworkCore.ChangeTracking.Internal.IStateManager> IResettableService

Constructors

ChangeTracker(DbContext)

This API supports the Entity Framework Core infrastructure and is not intended to be used directly from your code. This API may change or be removed in future releases.

ChangeTracker(DbContext, IStateManager, IChangeDetector, IModel, IEntityEntryGraphIterator)

This is an internal API that supports the Entity Framework Core infrastructure and not subject to the same compatibility standards as public APIs. It may be changed or removed without notice in any release. You should only use it directly in your code with extreme caution and knowing that doing so can result in application failures when updating to a new Entity Framework Core release.

ChangeTracker(IStateManager, IChangeDetector, IEntityEntryGraphIterator, DbContext)

This API supports the Entity Framework Core infrastructure and is not intended to be used directly from your code. This API may change or be removed in future releases.

Properties

AutoDetectChangesEnabled

Gets or sets a value indicating whether the DetectChanges() method is called automatically by methods of DbContext and related classes.

The default value is true. This ensures the context is aware of any changes to tracked entity instances before performing operations such as SaveChanges() or returning change tracking information. If you disable automatic detect changes then you must ensure that DetectChanges() is called when entity instances have been modified. Failure to do so may result in some changes not being persisted during SaveChanges() or out-of-date change tracking information being returned.

CascadeDeleteTiming

Gets or sets a value indicating when a dependent/child entity will have its state set to Deleted once its parent/principal entity has been marked as Deleted. The default value isImmediate.

Dependent/child entities are only deleted automatically when the relationship is configured with Cascade. This is set by default for required relationships.

Context

Gets the context this change tracker belongs to.

DebugView

Expand this property in the debugger for a human-readable view of the entities being tracked.

Warning: Do not rely on the format of the debug strings. They are designed for debugging only and may change arbitrarily between releases.

DeleteOrphansTiming

Gets or sets a value indicating when a dependent/child entity will have its state set to Deleted once severed from a parent/principal entity through either a navigation or foreign key property being set to null. The default value is Immediate.

Dependent/child entities are only deleted automatically when the relationship is configured with Cascade. This is set by default for required relationships.

LazyLoadingEnabled

Gets or sets a value indicating whether navigation properties for tracked entities will be loaded on first access.

The default value is true. However, lazy loading will only occur for navigation properties of entities that have also been configured in the model for lazy loading.

QueryTrackingBehavior

Gets or sets the tracking behavior for LINQ queries run against the context. Disabling change tracking is useful for read-only scenarios because it avoids the overhead of setting up change tracking for each entity instance. You should not disable change tracking if you want to manipulate entity instances and persist those changes to the database using SaveChanges().

This method sets the default behavior for the context, but you can override this behavior for individual queries using the AsNoTracking<TEntity>(IQueryable<TEntity>) and AsTracking<TEntity>(IQueryable<TEntity>) methods.

The default value is TrackAll. This means the change tracker will keep track of changes for all entities that are returned from a LINQ query.

Methods

AcceptAllChanges()

Accepts all changes made to entities in the context. It will be assumed that the tracked entities represent the current state of the database. This method is typically called by SaveChanges() after changes have been successfully saved to the database.

CascadeChanges()

Forces immediate cascading deletion of child/dependent entities when they are either severed from a required parent/principal entity, or the required parent/principal entity is itself deleted. See DeleteBehavior.

This method is usually used when CascadeDeleteTiming and/or DeleteOrphansTiming have been set to Never to manually force the deletes to have at a time controlled by the application.

If AutoDetectChangesEnabled is true then this method will call DetectChanges().

Clear()

Stops tracking all currently tracked entities.

DbContext is designed to have a short lifetime where a new instance is created for each unit-of-work. This manner means all tracked entities are discarded when the context is disposed at the end of each unit-of-work. However, clearing all tracked entities using this method may be useful in situations where creating a new context instance is not practical.

This method should always be preferred over detaching every tracked entity. Detaching entities is a slow process that may have side effects. This method is much more efficient at clearing all tracked entities from the context.

Note that this method does not generate StateChanged events since entities are not individually detached.

DetectChanges()

Scans the tracked entity instances to detect any changes made to the instance data. DetectChanges() is usually called automatically by the context when up-to-date information is required (before SaveChanges() and when returning change tracking information). You typically only need to call this method if you have disabled AutoDetectChangesEnabled.

Entries()

Gets an EntityEntry for each entity being tracked by the context. The entries provide access to change tracking information and operations for each entity.

Entries<TEntity>()

Gets an EntityEntry for all entities of a given type being tracked by the context. The entries provide access to change tracking information and operations for each entity.

Equals(Object)

Determines whether the specified object is equal to the current object.

GetHashCode()

Serves as the default hash function.

HasChanges()

Checks if any new, deleted, or changed entities are being tracked such that these changes will be sent to the database if SaveChanges() or SaveChangesAsync(CancellationToken) is called.

Note that this method calls DetectChanges() unless AutoDetectChangesEnabled has been set to false.

ToString()

Returns a string that represents the current object.

TrackGraph(Object, Action<EntityEntryGraphNode>)

Begins tracking an entity and any entities that are reachable by traversing it's navigation properties. Traversal is recursive so the navigation properties of any discovered entities will also be scanned. The specified callback is called for each discovered entity and must set the State that each entity should be tracked in. If no state is set, the entity remains untracked.

This method is designed for use in disconnected scenarios where entities are retrieved using one instance of the context and then changes are saved using a different instance of the context. An example of this is a web service where one service call retrieves entities from the database and another service call persists any changes to the entities. Each service call uses a new instance of the context that is disposed when the call is complete.

If an entity is discovered that is already tracked by the context, that entity is not processed (and it's navigation properties are not traversed).

TrackGraph<TState>(Object, TState, Func<EntityEntryGraphNode,TState,Boolean>)

Begins tracking an entity and any entities that are reachable by traversing it's navigation properties. Traversal is recursive so the navigation properties of any discovered entities will also be scanned. The specified callback is called for each discovered entity and must set the State that each entity should be tracked in. If no state is set, the entity remains untracked.

This method is designed for use in disconnected scenarios where entities are retrieved using one instance of the context and then changes are saved using a different instance of the context. An example of this is a web service where one service call retrieves entities from the database and another service call persists any changes to the entities. Each service call uses a new instance of the context that is disposed when the call is complete.

Typically traversal of the graph should stop whenever an already tracked entity is encountered or when an entity is reached that should not be tracked. For this typical behavior, use the TrackGraph(Object, Action<EntityEntryGraphNode>) overload. This overload, on the other hand, allows the callback to decide when traversal will end, but the onus is then on the caller to ensure that traversal will not enter an infinite loop.

TrackGraph<TState>(Object, TState, Func<EntityEntryGraphNode<TState>,Boolean>)

Begins tracking an entity and any entities that are reachable by traversing it's navigation properties. Traversal is recursive so the navigation properties of any discovered entities will also be scanned. The specified callback is called for each discovered entity and must set the State that each entity should be tracked in. If no state is set, the entity remains untracked.

This method is designed for use in disconnected scenarios where entities are retrieved using one instance of the context and then changes are saved using a different instance of the context. An example of this is a web service where one service call retrieves entities from the database and another service call persists any changes to the entities. Each service call uses a new instance of the context that is disposed when the call is complete.

Typically traversal of the graph should stop whenever an already tracked entity is encountered or when an entity is reached that should not be tracked. For this typical behavior, use the TrackGraph(Object, Action<EntityEntryGraphNode>) overload. This overload, on the other hand, allows the callback to decide when traversal will end, but the onus is then on the caller to ensure that traversal will not enter an infinite loop.

Events

StateChanged

An event fired when an entity that is tracked by the associated DbContext has moved from one EntityState to another.

Note that this event does not fire for entities when they are first tracked by the context. Use the Tracked event to get notified when the context begins tracking an entity.

Tracked

An event fired when an entity is tracked by the context, either because it was returned from a tracking query, or because it was attached or added to the context.

Explicit Interface Implementations

IInfrastructure<IStateManager>.Instance
Obsolete.

Gets the internal state manager being used to store information about tracked entities.

This property is intended for use by extension methods. It is not intended to be used in application code.

IResettableService.ResetState()
IResettableService.ResetStateAsync(CancellationToken)

Extension Methods

ToDebugString(ChangeTracker, ChangeTrackerDebugStringOptions, Int32)

Creates a human-readable representation of the given metadata.

Warning: Do not rely on the format of the returned string. It is designed for debugging only and may change arbitrarily between releases.

GetInfrastructure<T>(IInfrastructure<T>)

Gets the value from a property that is being hidden using IInfrastructure<T>.

This method is typically used by database providers (and other extensions). It is generally not used in application code.

IInfrastructure<T> is used to hide properties that are not intended to be used in application code but can be used in extension methods written by database providers etc.

Applies to