EntityDataSource.Include Property

Definition

Namespace:

System.Web.UI.WebControls

Assembly:

System.Web.Entity.dll

Gets or sets the expression that specifies the related objects to include in the query results.

public:
 property System::String ^ Include { System::String ^ get(); void set(System::String ^ value); };

public string Include { get; set; }

member this.Include : string with get, set

Public Property Include As String

Property Value

String

Comma-separated list of query paths to return in the query results.

Examples

The following XML markup defines a query path that returns SalesOrderHeader objects related to the returned Contact object. With each SalesOrderHeader, the related SalesOrderDetail and Address objects are also returned.

<asp:EntityDataSource ID="ContactDataSource" runat="server"
    AutoGenerateWhereClause="True" ConnectionString="name=AdventureWorksEntities"
    DefaultContainerName="AdventureWorksEntities" EnableDelete="True"
    EnableInsert="True" EnableUpdate="True" EntitySetName="Contact"
    Include="SalesOrderHeader.SalesOrderDetail, SalesOrderHeader.Address">
    <WhereParameters>
        <asp:ControlParameter ControlID="customerId" Name="ContactID"
            PropertyName="Text" />
    </WhereParameters>
</asp:EntityDataSource>

The previous XML example is the same as the following ObjectQuery<T> named customers:

ObjectQuery<Contact> customers =
      context.Contact
       .Where("it.ContactID = @ContactID",
         new ObjectParameter("ContactID", customerId))
        .Include("SalesOrderHeader.SalesOrderDetail")
        .Include("SalesOrderHeader.Address");

Remarks

The Include property of the EntityDataSource control specifies a comma-separated list of query paths that define the objects that are returned together with the specifically queried object. Each comma-separated value in the string is passed, without modification, as a separate call to the Include method of an ObjectQuery<T> that is executed by the Entity Framework. This query is the source of the data regulated by the EntityDataSource control. The Include property is the argument applied to the ObjectQuery<T> before it is executed.

The string supplied to the Include property uses the same format as the string that is passed to the Include method of ObjectQuery<T>. For examples of how to use query paths to automatically load related objects, see How to: Use Query Paths to Shape Results.

When the Include property is used to specify query paths, the properties of the related entities can only be used for read-only data-binding. If related objects are not explicitly included in the query path, the property descriptors are still available for data binding, but the properties themselves return null values. In this case, the related objects must be explicitly loaded to display their values. For more information, see Loading Related Objects.