Provides for immediate loading and filtering of related data.
Public NotInheritable Class DataLoadOptions
The DataLoadOptions type exposes the following members.
Initializes a new instance of the DataLoadOptions class.
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. (For more information, see Querying Across Relationships.)
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.
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
and AssociateWith directives must not create cycles. The following represent examples of such graphs:
Example 1: Self recursive
Example 2: Back-pointers
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
Example 5: Longer recursive subqueries
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.
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.
Supported in: 4.5.3, 4, 3.5
.NET Framework Client Profile
Supported in: 4
Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Any public static
in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.