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.
Assembly: System.Web.Extensions (in System.Web.Extensions.dll)
[ToolboxBitmapAttribute(typeof(LinqDataSource), L"LinqDataSource.ico")] [AspNetHostingPermissionAttribute(SecurityAction::LinkDemand, Level = AspNetHostingPermissionLevel::Minimal)] [AspNetHostingPermissionAttribute(SecurityAction::InheritanceDemand, Level = AspNetHostingPermissionLevel::Minimal)] public ref class LinqDataSource : public DataSourceControl
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 control enables you to use LINQ in an ASP.NET Web page by setting properties in markup text. The 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 control applies data operations in the following order:
Where (specify which data records to return).
Order By (sort).
Group By (aggregate data records that share values).
Order Groups By (sort grouped data).
Select (specify which fields or properties to return).
Auto-sort (sort data records by a property that the user has selected).
Auto-page (retrieve a subset of data records that were selected by the user).
You use the OrderBy property to specify the names of properties from the returned data to sort by.
When you use the 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 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 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:
The Select property cannot be assigned a value.
The GroupBy property cannot be assigned a value.
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.
You use the 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 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 control to display the data.
The following example shows a control that enables users to update, delete, and insert records in the data source. A DetailsView control is bound to the 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.
The following example shows a 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.
The following example shows two ListView controls that display the data from the 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.
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.