• Article

DataLoadOptions Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Provides for immediate loading and filtering of related data.

Inheritance Hierarchy

System.Object
  System.Data.Linq.DataLoadOptions

Namespace:  System.Data.Linq
Assembly:  System.Data.Linq (in System.Data.Linq.dll)

Syntax

'Declaration
Public NotInheritable Class DataLoadOptions

public sealed class DataLoadOptions

The DataLoadOptions type exposes the following members.

Constructors

  Name Description
Public methodSupported by Silverlight for Windows Phone DataLoadOptions Initializes a new instance of the DataLoadOptions class.

Top

Methods

  Name Description
Public methodSupported by Silverlight for Windows Phone AssociateWith(LambdaExpression) Filters the objects retrieved for a particular relationship.
Public methodSupported by Silverlight for Windows Phone AssociateWith<T>(Expression<Func<T, Object>>) Filters objects retrieved for a particular relationship.
Public methodSupported by Silverlight for Windows Phone Equals(Object) Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodSupported by Silverlight for Windows Phone Finalize Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by Silverlight for Windows Phone GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public methodSupported by Silverlight for Windows Phone GetType Gets the Type of the current instance. (Inherited from Object.)
Public methodSupported by Silverlight for Windows Phone LoadWith(LambdaExpression) Retrieves specified data related to the main target by using a lambda expression.
Public methodSupported by Silverlight for Windows Phone LoadWith<T>(Expression<Func<T, Object>>) Specifies which sub-objects to retrieve when a query is submitted for an object of type T.
Protected methodSupported by Silverlight for Windows Phone MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by Silverlight for Windows Phone ToString Returns a string that represents the current object. (Inherited from Object.)

Top

Remarks

General

When you query for an object, you actually retrieve only the object you requested. The related objects are not automatically fetched at the same time.

The DataLoadOptions class provides two methods to achieve immediate loading of specified related data. The LoadWith method allows for immediate loading of data related to the main target. The AssociateWith method allows for filtering related objects.

Rules

Note the following rules regarding DataLoadOptions usage:

  • Assigning a DataLoadOptions to a DataContext after the first query has been executed generates an exception.

  • Modifying a DataLoadOptions after it has been assigned to a DataContext generates an exception.

Cycle Handling

LoadWith and AssociateWith directives must not create cycles. The following represent examples of such graphs:

  • Example 1: Self recursive

    • dlo.LoadWith<Employee>(e => e.Reports);

  • Example 2: Back-pointers

    • dlo.LoadWith <Customer>(c => C.Orders);

    • dlo.LoadWith <Order>(o => o.Customer);

  • Example 3: Longer cycles

    Although this should not occur in a well-normalized model, it is possible.

    • dlo.LoadWith <A>(a => a.Bs);

    • dlo.LoadWith <B>(b => b.Cs);

    • dlo.LoadWith <C>(c => c.As);

  • Example 4: Self recursive subQueries

    • dlo.AssociateWith<A>(a=>a.As.Where(a=>a.Id=33));

  • Example 5: Longer recursive subqueries

    • dlo.AssociateWith<A>(a=>a.Bs.Where(b=>b.Id==3));

    • dlo.AssociateWith<B>(b=>b.As.Where(a=>a.Id==3));

The following are some general rules that help you understand what occurs in these scenarios.

LoadWith Each call to LoadWith checks whether cycles have been introduced into the graph. If there are, as in Examples 1, 2, and 3, an exception is thrown.

AssociateWith The engine at run time does not apply the existing SubQuery clauses to the relationship inside the expression.

  • In Example 4, the Where clause is executed against all A, not just the ones sub-filtered by the SubQuery expression itself (because that would be recursive)

  • In Example 5, the first Where clause is applied to all the Bs, even though there are subqueries on B. The second Where clause is applied to all the As even though there are subqueries on A.

Topic Location
How to: Filter at the DataContext Level (LINQ to SQL) LINQ to SQL
How to: Retrieve Many Objects At Once (LINQ to SQL) LINQ to SQL
Customizing Operations: Overview (LINQ to SQL) LINQ to SQL
Deferred versus Immediate Loading (LINQ to SQL) LINQ to SQL
How to: Filter Related Data (LINQ to SQL) LINQ to SQL
How to: Control How Much Related Data Is Retrieved (LINQ to SQL) LINQ to SQL
How to: Filter at the DataContext Level (LINQ to SQL) LINQ to SQL
How to: Retrieve Many Objects At Once (LINQ to SQL) LINQ to SQL
Customizing Operations: Overview (LINQ to SQL) LINQ to SQL
Deferred versus Immediate Loading (LINQ to SQL) LINQ to SQL
How to: Filter Related Data (LINQ to SQL) LINQ to SQL
How to: Control How Much Related Data Is Retrieved (LINQ to SQL) LINQ to SQL

Examples

When you retrieve Customers from the Northwind sample database, you can use DataLoadOptions to specify that Orders is also to be retrieved. You can even specify which subset of Orders to retrieve.

Version Information

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

System.Data.Linq Namespace