MSDN Documentation

.NET Concepts > Data Access > ADO.NET > Entity Framework

Understanding Entity State in Entity Framework

Entity Framework (EF) plays a crucial role in object-relational mapping (ORM) for .NET applications. A key concept within EF is the Entity State, which tracks the current status of an entity object within the context. This state dictates how EF will interact with the underlying database when changes are saved.

The Role of the DbContext

The DbContext is the gateway to interacting with your data in Entity Framework. It manages a collection of entity objects that are either in memory or have been loaded from the database. Each entity object tracked by the DbContext has an associated EntityState.

When you retrieve an entity, the DbContext automatically sets its state. When you modify an entity and call SaveChanges(), the DbContext inspects the state of each tracked entity and generates the appropriate SQL commands (INSERT, UPDATE, DELETE) to persist those changes to the database.

Common Entity States

The System.Data.EntityState enumeration defines the possible states an entity can be in. Here are the most commonly encountered states:

Added

The entity has been created and added to the context, but it has not yet been persisted to the database. EF will generate an INSERT statement for this entity.

Modified

The entity was loaded from the database, and one or more of its properties have been changed. EF will generate an UPDATE statement for this entity.

Deleted

The entity was loaded from the database and has been marked for deletion. EF will generate a DELETE statement for this entity.

Unchanged

The entity was loaded from the database, and none of its properties have been modified since it was loaded or last saved. EF does not perform any database operation for unchanged entities.

Detached

The entity is not currently tracked by the DbContext. This can happen if you create an entity outside the context or if it has been explicitly detached.

Managing Entity State

You can explicitly control the state of an entity within the DbContext using methods like:

  • DbContext.Add(entity): Sets the entity state to Added.
  • DbContext.Remove(entity): Sets the entity state to Deleted.
  • DbContext.Update(entity): Sets the entity state to Modified.
  • DbContext.Entry(entity).State = EntityState.Modified;: Manually sets the state.
  • DbContext.Entry(entity).State = EntityState.Unchanged;: Marks an entity as unchanged.
  • DbContext.Entry(entity).State = EntityState.Detached;: Detaches an entity.

Example: Adding and Modifying an Entity


using (var context = new MyDbContext())
{
    // 1. Adding a new entity
    var newProduct = new Product { Name = "New Gadget", Price = 199.99m };
    context.Products.Add(newProduct); // State is now Added
    // Or explicitly: context.Entry(newProduct).State = EntityState.Added;

    // 2. Retrieving an existing entity and modifying it
    var existingProduct = context.Products.Find(1);
    if (existingProduct != null)
    {
        existingProduct.Price = 209.99m; // State is now Modified
        // Or explicitly: context.Entry(existingProduct).State = EntityState.Modified;
    }

    // 3. Saving changes
    context.SaveChanges();
}

Example: Deleting an Entity


using (var context = new MyDbContext())
{
    var productToDelete = context.Products.Find(5);
    if (productToDelete != null)
    {
        context.Products.Remove(productToDelete); // State is now Deleted
        // Or explicitly: context.Entry(productToDelete).State = EntityState.Deleted;
    }

    context.SaveChanges();
}

Entity State Property Detective

The DbEntityEntry object, obtained via DbContext.Entry(entity), provides detailed information about the entity and its state. You can access properties like:

  • State: The current EntityState.
  • OriginalValues: A snapshot of the original property values.
  • CurrentValues: The current property values.
  • IsModified: A boolean indicating if the entity has been modified.

This detective capability is powerful for auditing, complex update scenarios, and understanding precisely what EF will do.

Conclusion

Understanding Entity State is fundamental to effectively using Entity Framework. By correctly managing the state of your entities, you ensure that your data operations are efficient and accurate, leading to robust and performant data access in your .NET applications.