EntityCollection<TEntity>.Load(MergeOption) Method

Definition

Namespace:

System.Data.Objects.DataClasses

Assembly:

System.Data.Entity.dll

Loads related objects into the collection, using the specified merge option.

public:
 override void Load(System::Data::Objects::MergeOption mergeOption);

public override void Load (System.Data.Objects.MergeOption mergeOption);

override this.Load : System.Data.Objects.MergeOption -> unit

Public Overrides Sub Load (mergeOption As MergeOption)

Parameters

mergeOption

MergeOption

Specifies how the objects in this collection should be merged with the objects that might have been returned from previous queries against the same ObjectContext.

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 loads the related SalesOrderHeader objects for the Contact entity.

// Specify the customer ID.
int contactID = 4332;

using (AdventureWorksEntities context =
    new AdventureWorksEntities())
{
    context.ContextOptions.LazyLoadingEnabled = false;

    // Get a specified customer by contact ID.
    var contact =
        (from c in context.Contacts
         where c.ContactID == contactID
         select c).First();

    // Load the orders for the customer explicitly.
    if (!contact.SalesOrderHeaders.IsLoaded)
    {
        contact.SalesOrderHeaders.Load();
    }

    foreach (SalesOrderHeader order in contact.SalesOrderHeaders)
    {
        // Load the items for the order if not already loaded.
        if (!order.SalesOrderDetails.IsLoaded)
        {
            order.SalesOrderDetails.Load();
        }

        Console.WriteLine(String.Format("PO Number: {0}",
            order.PurchaseOrderNumber));
        Console.WriteLine(String.Format("Order Date: {0}",
            order.OrderDate.ToString()));
        Console.WriteLine("Order items:");
        foreach (SalesOrderDetail item in order.SalesOrderDetails)
        {
            Console.WriteLine(String.Format("Product: {0} "
                + "Quantity: {1}", item.ProductID.ToString(),
                item.OrderQty.ToString()));
        }
    }
}

Remarks

This method calls the internal RelatedEnd.ValidateLoad method before loading the collection, which validates that a call to Load has the correct conditions. The RelatedEnd.ValidateLoad method checks that:

• A valid ObjectContext exists.
• The entity isn't in a Deleted state.
• MergeOption for Load must be NoTracking if and only if the source entity was NoTracking. If the source entity was retrieved with any other MergeOption, the Load MergeOption can be anything but NoTracking (for example, the entity could have been loaded with OverwriteChanges and the Load option can be AppendOnly).
• If mergeOption is NoTracking, Load isn't called on an already loaded entity and Load isn't called on a non-empty, not-tracked RelatedEnd.

When objects in the collection are already loaded into the ObjectContext, the Load method enforces the MergeOption specified by the mergeOption parameter. For more information, see Identity Resolution, State Management, and Change Tracking.

To explicitly load related objects, you must call the Load method on the related end returned by the navigation property. For a one-to-many relationship, call the Load method on EntityCollection<TEntity>. For a one-to-one relationship, call the Load on EntityReference<TEntity>. This loads the related object data into the object context. You can enumerate through the collection of returned results using a foreach loop (For Each...Next in Visual Basic) and conditionally call the Load method on EntityReference<TEntity> and EntityCollection<TEntity> properties for each entity in the results.

The Load method loads related objects from the data source whether or not IsLoaded is true.

Note

When you call the Load method during a foreach (C#) or For Each (Visual Basic) enumeration, Object Services tries to open a new data reader. This operation will fail unless you have enabled multiple active results sets by specifying multipleactiveresultsets=true in the connection string. You can also load the result of the query into a List<T> collection. This closes the data reader and enables you to enumerate over the collection to load referenced objects.

The EntityCollection<TEntity>.Load method is synchronized with the EntityReference<TEntity>.Load method.