EntityCollection<TEntity>.Attach Method

Definition

Namespace:

System.Data.Objects.DataClasses

Assembly:

System.Data.Entity.dll

Defines a relationship between two attached objects in an object context.

Overloads

Attach(IEnumerable<TEntity>)	Defines relationships between an object and a collection of related objects in an object context.
Attach(TEntity)	Defines a relationship between two attached objects in an object context.

Attach(IEnumerable<TEntity>)

Defines relationships between an object and a collection of related objects in an object context.

public:
 void Attach(System::Collections::Generic::IEnumerable<TEntity> ^ entities);

public void Attach (System.Collections.Generic.IEnumerable<TEntity> entities);

override this.Attach : seq<'Entity (requires 'Entity : null)> -> unit

Public Sub Attach (entities As IEnumerable(Of TEntity))

Parameters

entities

IEnumerable<TEntity>

Collection of objects in the object context that are related to the source object.

Exceptions

ArgumentNullException

entities collection is null.

InvalidOperationException

The source object or an object in the entities collection is null or is not in an Unchanged or Modified state.

-or-

The relationship cannot be defined based on the EDM metadata. This can occur when the association in the conceptual schema does not support a relationship between the two types.

Remarks

The Attach method is used to define relationships between an object and a collection of related objects when both the source object and the collection of related objects already exist in the object context. To attach an object or an object graph where the relationships are already defined, call the Attach method on the ObjectContext. To create a new object that is related to the source object, call the Add method on the EntityCollection<TEntity>. For more information, see Attaching and Detaching Objects.

If the collection is already filled or partially filled, the Attach method merges existing entities with the given entities. The given entities are not assumed to be the complete set of related entities.

All entities passed in must be in the Unchanged or Modified state. Objects in the Deleted state are only allowed when the state manager is already tracking the relationship instance.

Attach(TEntity)

Defines a relationship between two attached objects in an object context.

public:
 void Attach(TEntity entity);

public void Attach (TEntity entity);

override this.Attach : 'Entity -> unit

Public Sub Attach (entity As TEntity)

Parameters

entity

TEntity

The object being attached.

Exceptions

ArgumentNullException

When the entity is null.

InvalidOperationException

When the entity cannot be related to the source object. This can occur when the association in the conceptual schema does not support a relationship between the two types.

-or-

When either object is null or is not in an Unchanged or Modified state.

Examples

This example is based on the Adventure Works Sales Model. To run the code in this example, you must have already added the AdventureWorks Sales Model to your project and configured your project to use the Entity Framework. To do this, complete the procedures in How to: Manually Configure an Entity Framework Project and How to: Manually Define the Model and Mapping Files.

This example attaches a collection of detached SalesOrderDetail objects and a detached SalesOrderHeader object to an object context, and then defines the relationships between the SalesOrderHeader object and each SalesOrderDetail object.

private static void AttachRelatedObjects(
    ObjectContext currentContext,
    SalesOrderHeader detachedOrder,
    List<SalesOrderDetail> detachedItems)
{
    // Attach the root detachedOrder object to the supplied context.
    currentContext.Attach(detachedOrder);

    // Attach each detachedItem to the context, and define each relationship
    // by attaching the attached SalesOrderDetail object to the EntityCollection on
    // the SalesOrderDetail navigation property of the now attached detachedOrder.
    foreach (SalesOrderDetail item in detachedItems)
    {
        currentContext.Attach(item);
        detachedOrder.SalesOrderDetails.Attach(item);
    }
}

Remarks

The Attach method is used to define relationships between two objects when both objects already exist in the object context. To attach an object or an object graph where the relationships are already defined, call the Attach method on the ObjectContext. To create a new object that is related to the source object, call the Add method on the EntityCollection<TEntity>. For more information, see Attaching and Detaching Objects.

If the EntityCollection<TEntity> already has loaded objects, the Attach method merges the object together with the existing objects in the EntityCollection<TEntity>.

The attached object is not assumed to be the complete set of related entity objects.

The object associated with this EntityCollection<TEntity> and all objects being attached to it must be in an Unchanged or Modified state.

Objects in the Deleted state can only be attached when the ObjectStateManager is already tracking the relationship instance.