This documentation is archived and is not being maintained.

LinqDataSource Class

Updated: February 2010

Enables the use of Language-Integrated Query (LINQ) in an ASP.NET Web page through markup text to retrieve and modify data from a data object.

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

<ToolboxBitmapAttribute(GetType(LinqDataSource), "LinqDataSource.ico")> _
<AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
Public Class LinqDataSource _
	Inherits DataSourceControl
Dim instance As LinqDataSource
<asp:LinqDataSource />

Language-Integrated Query (LINQ) is a query syntax that defines a set of query operators that enable traversal, filter, and projection operations to be expressed in a declarative way in any .NET-based programming language. The data object can be an in-memory data collection or an object that represents data from a database. You can retrieve or modify the data without having to write SQL commands for each operation.

The LinqDataSource control enables you to use LINQ in an ASP.NET Web page by setting properties in markup text. The LinqDataSource control uses LINQ to SQL to automatically generate the data commands. For more information about LINQ to SQL, see LINQ to SQL.

When you are retrieving data from an in-memory data collection, you set the ContextTypeName property to the class that contains the data collection. You set the TableName property to the property or field that returns the data collection. For example, you might have a class named Person that contains a property named FavoriteCities that returns an array of string values. In that case, you set the ContextTypeName property to Person and set the TableName property to FavoriteCities.

When you are querying a database, you must first create entity classes that represent the database and its tables. You can use the Object Relational Designer or the SqlMetal.exe utility to generate these classes. You then set the ContextTypeName property to the class that represents the database and set the TableName property to the property that represents the database table.

The LinqDataSource control applies data operations in the following order:

  1. Where (specify which data records to return).

  2. Order By (sort).

  3. Group By (aggregate data records that share values).

  4. Order Groups By (sort grouped data).

  5. Select (specify which fields or properties to return).

  6. Auto-sort (sort data records by a property that the user has selected).

  7. Auto-page (retrieve a subset of data records that were selected by the user).

You can add conditions to the Where property to filter the data records that are returned from a query. If the Where property is not set, the LinqDataSource control retrieves every record from the data object.

You use the OrderBy property to specify the names of properties from the returned data to sort by.


When you use the LinqDataSource control with SQL Server 2000 or SQL Server Compact 3.5 and the AutoPage property is set to true, you must provide a value in the OrderBy property. By default, the AutoPage property is true. If you assign a value to the Select property, you must also include all identity columns in the list of properties that is returned in the query.

You use the GroupBy property to specify which properties are used to consolidate data records that have the same values. When you group data, you can include Key and It, which are dynamically created properties, in the Select property. The Key property refers to the values in the property or properties that were used to group the data. For example, if you group by a property named Category, the Key property will contain all unique values in the Category property. The It property refers to a collection of individual records in a grouping of data. You can iterate over the It property to retrieve the individual records that have been consolidated in the grouping operation. For example, if you group by a property named Category, the It property contains all the individual records that share a common value in the Category property.

You use the OrderGroupsBy property to specify the properties to use for sorting the grouped data. When you group data, the OrderBy property specifies how the individual records within the grouped data are sorted.

By default, the LinqDataSource control retrieves values for all the properties from a data object. You use the Select property to specify which properties to return if you want to work with a subset of available properties. The Select operation is applied after the Where, Order By, and Group By operations. Therefore, if you create an aliased name in a Select clause, the alias is not available in the other clauses.

You can specify whether data modifications are enabled by using the EnableDelete, EnableInsert, and EnableUpdate properties. The user interface for modifying data from a LinqDataSource control is typically provided through a data-bound control, such as a DetailsView control. In addition to setting EnableDelete, EnableInsert, or EnableUpdate to true, the following conditions are required to enable automatic data modifications:

You can restrict which properties are displayed in a data-bound control in two ways. You can either set the Select property to a subset of properties, or you can define the fields for a data-bound control by adding DataControlField controls. However, if you set the Select property, it means that automatic update, insert, and delete operations cannot be enabled. If you want to enable automatic data modifications while you work with a subset of available properties, do not set the Select property. Instead, retrieve all properties from the data object and manage which ones are displayed by using the data-bound control. When you use the DetailsView control or the GridView control, you must also set the AutoGenerateRows or AutoGenerateColumns properties to false. This prevents the data-bound control from automatically including buttons for editing and deleting the data. Any values that are not displayed in the data-bound control are stored in view state. They are passed unchanged to the data source when the data update is performed.

If you have to evaluate values at run time for ordering, filtering, or grouping values, you can add parameters to the WhereParameters, GroupByParameters, OrderGroupsByParameters, or OrderByParameters collections.

If you want to specify default values, you can add parameters to the InsertParameters collection.

If you want to examine or modify values before the data operation is executed, you can handle the Deleting, Inserting, Selecting, or Updating events. You can also handle these events in order to cancel the data operation or to examine validation errors that occurred when you set properties in the data class based on user input.

To examine values after the data operation has finished, handle the Deleted, Inserted, Selected, or Updated events.

You use the LinqDataSource control to retrieve data from a stored procedure by creating an event handler for the Selecting event. In the event handler, you call the method in the data context class that represents the stored procedure and set the result to the Result property of the LinqDataSourceSelectEventArgs object. If you want to enable automatic update, insert, and delete operations for the data, the type that is returned from the method must match the type that is specified in the TableName property. For more information about creating data context methods, see How to: Create DataContext Methods Mapped to Stored Procedures and Functions (O/R Designer).

The following example shows a LinqDataSource control that retrieves data from an entity class named Products. The entity class could have been generated by using the O/R Designer or the SqlMetal.exe utility. The Where property is set to return only records that have a value in the Price property greater than 50. A GridView control is bound to the LinqDataSource control to display the data.

    Where="Price > 50"

The following example shows a LinqDataSource control that enables users to update, delete, and insert records in the data source. A DetailsView control is bound to the LinqDataSource control and enables users to see and modify the data. Notice that no SQL commands are required in order to select, update, delete, or insert the records.


The following example shows an event handler for the Selecting event that sets the data object based on a value in the Web page.

Partial Class Default3
    Inherits System.Web.UI.Page

    Dim citiesArray() As String = _
    { _
        "Atlanta", _
        "Charlotte", _
        "Denver", _
        "New York", _
        "San Francisco" _

    Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load

    End Sub 

    Protected Sub LinqDataSource_Selecting(ByVal sender As Object, ByVal e As System.Web.UI.WebControls.LinqDataSourceSelectEventArgs) Handles LinqDataSource1.Selecting
        Dim cities = From city In citiesArray _
                     Where city > "B" _
                     Select city
        e.Result = cities
        ' Or we could set e.Result = citiesArray to return all rows. 
    End Sub 

End Class

The following example shows a LinqDataSource control that is configured to group by two columns. The Key property references an object that has two properties, ProductCategory and Color. The object represented by It is renamed (aliased) to Products. The renamed Products object contains a collection of the individual records in a grouping. Each instance will contain all the columns from the Products table.

  GroupBy="new(ProductCategory, Color)" 
          It As Products,
          Max(ListPrice) As MaxListPrice, 
          Min(ListPrice) As MinListPrice)"

The following example shows two ListView controls that display the data from the LinqDataSource control in the previous example. One ListView control displays the grouped data, and the other ListView control displays the individual names of products that belong to that group. The nested data-bound control's DataSource property is set to Products, which is the alias for the It object.

   ID="ListView1" runat="server">

     <table id="Table1" 

           <th><b>Product Category</b></th>
           <th><b>Highest Price</b></th>
           <th><b>Lowest Price</b></th>
       <tr runat="server" id="itemPlaceholder">


       <td><%# Eval("key.ProductCategory") %></td>
       <td><%# Eval("key.Color") %></td>
       <td><%# Eval("MaxListPrice") %></td>
       <td><%# Eval("MinListPrice") %></td>

       <td colspan="4" style="width:100%;background-color:White;color:Black">
           DataSource='<%# Eval("Products") %>' 

             <div runat="server" id="itemPlaceholder" />

             <%# Eval("ProductName") %><br />



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

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003

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

.NET Framework

Supported in: 3.5




February 2010

Removed references to Update and Delete parameters collections because they are not used.

Customer feedback.