DataLoadOptions Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Provides for immediate loading and filtering of related data.
public ref class DataLoadOptions sealed
public sealed class DataLoadOptions
type DataLoadOptions = class
Public NotInheritable Class DataLoadOptions
- Inheritance
-
DataLoadOptions
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.
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. (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.
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 allA
, 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 theB
s, even though there are subqueries onB
. The secondWhere
clause is applied to all theA
s even though there are subqueries onA
.
Constructors
DataLoadOptions() |
Initializes a new instance of the DataLoadOptions class. |
Methods
AssociateWith(LambdaExpression) |
Filters the objects retrieved for a particular relationship. |
AssociateWith<T>(Expression<Func<T,Object>>) |
Filters objects retrieved for a particular relationship. |
Equals(Object) |
Determines whether the specified object is equal to the current object. (Inherited from Object) |
GetAssociationCriteria(MemberInfo, LambdaExpression) | |
GetHashCode() |
Serves as the default hash function. (Inherited from Object) |
GetType() |
Gets the Type of the current instance. (Inherited from Object) |
IsImmediate(MemberInfo) | |
LoadWith(LambdaExpression) |
Retrieves specified data related to the main target by using a lambda expression. |
LoadWith<T>(Expression<Func<T,Object>>) |
Specifies which sub-objects to retrieve when a query is submitted for an object of type T. |
MemberwiseClone() |
Creates a shallow copy of the current Object. (Inherited from Object) |
ToString() |
Returns a string that represents the current object. (Inherited from Object) |