This documentation is archived and is not being maintained.

EntityDataSource.Include Property

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

Namespace:  System.Web.UI.WebControls
Assembly:  System.Web.Entity (in System.Web.Entity.dll)

public string Include { get; set; }
<asp:EntityDataSource Include="String" />

Property Value

Type: System.String
Comma-separated list of query paths to return in the query results.

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 (Entity Framework).

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 Shaping Query Results (Entity Framework).

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">
        <asp:ControlParameter ControlID="customerId" Name="ContactID" 
            PropertyName="Text" />

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

ObjectQuery<Contact> customers =
       .Where("it.ContactID = @ContactID",
         new ObjectParameter("ContactID", customerId))

.NET Framework

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.