System.Web 2.0.0.0 System.Web.UI.DataSourceControl System.Drawing.ToolboxBitmap("bitmap file goes here") System.Web.UI.PersistChildren(false) System.Web.UI.ParseChildren(true) System.ComponentModel.Designer("System.Web.UI.Design.WebControls.ObjectDataSourceDesigner, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.ComponentModel.Design.IDesigner") System.ComponentModel.DefaultProperty("TypeName") System.ComponentModel.DefaultEvent("Selecting") In this topic: Introduction Purpose Retrieving Data Performing Data Operations Filtering Data Caching Features Data View Using LINQ to SQL Declarative Syntax

Introduction

An control works with a class that you create. You create methods that retrieve and update data, and you provide the names of those methods to the control in markup. During rendering or postback processing, the calls the methods that you have specified. There is no visual rendering of the control. As a result, the does not support visual features such as the or property.

Purpose

A very common application design practice is to separate the presentation layer from business logic and to encapsulate the business logic in business objects. These business objects form a distinct layer between the presentation layer and the data tier, resulting in a three-tier application architecture. The control enables developers to use an ASP.NET data source control while retaining their three-tier application architecture. The control uses reflection to create instances of business objects and to call methods on them to retrieve, update, insert, and delete data. The property identifies the name of the class that the works with. The control creates and destroys an instance of the class for each method call; it does not hold the object in memory for the lifetime of the Web request. This is a serious consideration if the business object that you use requires many resources or is otherwise expensive to create and destroy. Using an expensive object might not be an optimal design choice, but you can control the life cycle of the object by using the , , and events. The methods that are identified by the , , , and properties can be instance methods or static (Shared in Visual Basic) methods. If the methods are static (Shared in Visual Basic), an instance of the business object is not created, and the , , and events are not raised.

Retrieving Data

To retrieve data from a business object, set the property to the name of the method that retrieves data. If the method does not return an or object, the object is wrapped by the runtime in an collection. If the method signature has parameters, you can add objects to the collection, and then bind them to the values that you want to pass to the method that is specified by the property. In order for the control to use the parameters, the parameters must match the names and types of the parameters in the method signature. For more information, see
Using Parameters with the ObjectDataSource Control. The control retrieves data whenever the method is called. This method provides programmatic access to the method that is specified by property. The method that is specified by the property is called automatically by controls that are bound to the when their DataBind method is called. If you set the DataSourceID property of a data-bound control, the control automatically binds to data from the data source, as needed. Setting the DataSourceID property is the recommended method for binding an control to a data-bound control. Alternatively, you can set the DataSource property, but then you must explicitly call the DataBind method of the data-bound control. You can call the method programmatically at any time to retrieve data. For more information about binding data-bound controls to data source controls, see Binding to Data Using a Data Source Control.

Performing Data Operations

Depending on the capabilities of the business object that the control works with, you can perform data operations, such as updates, insertions, and deletions. To perform these data operations, set the appropriate method name and any associated parameters for the operation that you want to perform. For example, for an update operation, set the property to the name of the business object method that performs updates and add any required parameters to the collection. If the control is associated with a data-bound control, the parameters are added by the data-bound control. In this case, you need to ensure that the parameter names of the method match the field names in the data-bound control. The update is performed when the method is called, either explicitly by your code or automatically by a data-bound control. The same general pattern is followed for and operations. Business objects are assumed to perform these types of data operations one record at a time, rather than batched.

Filtering Data

The control can filter data that is retrieved by the property, if the data is returned as a or object. You can set the property to a filtering expression by using a format string syntax and bind values in the expression to parameters that are specified in the collection.

Caching

Although the does not retain the instance of the business object across multiple requests, it can cache the result of calling the method identified by the property. While the data is cached, subsequent calls to the method return the cached data instead of creating the business object and calling its using reflection. Caching lets you avoid creating the object and calling its data method at the expense of memory on the Web server. The automatically caches data when the property is set to true, and the property is set to the number of seconds that the cache stores data before the cache is discarded. You can also specify a property and an optional property. The control allows you to cache all types of data, but you should not cache objects that retain resources or state that cannot be shared to service multiple requests (for example, an open object), because the same instance of the object will be used to service multiple requests.

Features

The following table describes the features of the control. Capability Requirements Selecting Set the property to the name of the business object method that selects data, and include any necessary parameters in the collection either programmatically or by using a data-bound control. Sorting Set the property to the name of the parameter in the method that carries the sort criteria. Filtering Set the property to a filtering expression and optionally add any parameters to the collection to filter the data when the method is called. The method specified by the property must return a or . Paging Data source paging is supported, if the method contains parameters for the maximum number of records to retrieve and the index of the first record to retrieve. The names of those parameters must be set in the and properties, respectively. A data-bound control might be able to perform paging itself, even if the control does not support paging directly in the method specified by the property. The requirement for the data-bound control to be able to do this is that the method specified by the property return an object that implements the interface. Updating Set the property to the name of the business object method that updates data, and include any necessary parameters in the collection. Deleting Set the property to the name of the business object method or function that deletes data, and include any necessary parameters in the collection. Inserting Set the property to the name of the business object method or function that inserts data, and include any necessary parameters in the collection. Caching Set the property to true, and the and properties according to the caching behavior you want for your cached data. When you use the class to update or insert data, strings that are entered at the client are not automatically converted from the client culture format to the server culture format. For example, the client culture might specify DD/MM/YYYY as the date format, and the date format on the server might be MM/DD/YYYY. In that case, October 5, 2009 would be entered in a control as 5/10/2009 but would be interpreted as May 10, 2009. October 15, 2009 would be entered as 15/10/2009, and would be rejected as an invalid date.

Data View

As with all data source controls, the control is associated with a data source view class. While the control is the interface that the page developer uses to work with data, the class is the interface that data-bound controls work with. Additionally, the class describes the capabilities of the data source control, and performs the actual work. The control has only one associated , and it is always named DefaultView. While the object is exposed by the method, many of its properties and methods are wrapped and exposed directly by the control. Behind the scenes, the object performs all data operations, including retrieving, inserting, updating, deleting, filtering, and sorting the data. For more information, see .

Using LINQ to SQL

You can use the control with a LINQ to SQL class. To do so, you set the property to the name of the data-context class. You also set the , , , and methods to the methods in the data-context class that perform the corresponding operations. You must create an event handler for the event in order to cancel disposing of the data-context class. This step is necessary because LINQ to SQL supports deferred execution, whereas the control tries to dispose the data context after the Select operation. For more information about how to create LINQ to SQL classes, see
How to: Create LINQ to SQL Classes in a Web Application. For an example of how to cancel the disposing of a data context class, see the event.

Using the Entity Framework

You can also use the control with the Entity Framework. For more information, see Using the Entity Framework and the ObjectDataSource Control.

Declarative Syntax

<asp:ObjectDataSource     CacheDuration="string|Infinite"     CacheExpirationPolicy="Absolute|Sliding"     CacheKeyDependency="string"     ConflictDetection="OverwriteChanges|CompareAllValues"     ConvertNullToDBNull="True|False"     DataObjectTypeName="string"     DeleteMethod="string"     EnableCaching="True|False"     EnablePaging="True|False"     EnableTheming="True|False"     EnableViewState="True|False"     FilterExpression="string"     ID="string"     InsertMethod="string"     MaximumRowsParameterName="string"     OldValuesParameterFormatString="string"     OnDataBinding="DataBinding event handler"     OnDeleted="Deleted event handler"     OnDeleting="Deleting event handler"     OnDisposed="Disposed event handler"     OnFiltering="Filtering event handler"     OnInit="Init event handler"     OnInserted="Inserted event handler"     OnInserting="Inserting event handler"     OnLoad="Load event handler"     OnObjectCreated="ObjectCreated event handler"     OnObjectCreating="ObjectCreating event handler"     OnObjectDisposing="ObjectDisposing event handler"     OnPreRender="PreRender event handler"     OnSelected="Selected event handler"     OnSelecting="Selecting event handler"     OnUnload="Unload event handler"     OnUpdated="Updated event handler"     OnUpdating="Updating event handler"     runat="server"     SelectCountMethod="string"     SelectMethod="string"     SkinID="string"     SortParameterName="string"     SqlCacheDependency="string"     StartRowIndexParameterName="string"     TypeName="string"     UpdateMethod="string"     Visible="True|False" >         <DeleteParameters>                 <asp:ControlParameter                     ControlID="string"                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:CookieParameter                     ConvertEmptyStringToNull="True|False"                     CookieName="string"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:FormParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     FormField="string"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:Parameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:ProfileParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:QueryStringParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     QueryStringField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:SessionParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     SessionField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />         </DeleteParameters>         <FilterParameters>                 <asp:ControlParameter                     ControlID="string"                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:CookieParameter                     ConvertEmptyStringToNull="True|False"                     CookieName="string"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:FormParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     FormField="string"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:Parameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:ProfileParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:QueryStringParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     QueryStringField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:SessionParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     SessionField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />         </FilterParameters>         <InsertParameters>                 <asp:ControlParameter                     ControlID="string"                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:CookieParameter                     ConvertEmptyStringToNull="True|False"                     CookieName="string"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:FormParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     FormField="string"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:Parameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:ProfileParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:QueryStringParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     QueryStringField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:SessionParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     SessionField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />         </InsertParameters>         <SelectParameters>                 <asp:ControlParameter                     ControlID="string"                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:CookieParameter                     ConvertEmptyStringToNull="True|False"                     CookieName="string"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:FormParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     FormField="string"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:Parameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:ProfileParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:QueryStringParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     QueryStringField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:SessionParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     SessionField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />         </SelectParameters>         <UpdateParameters>                 <asp:ControlParameter                     ControlID="string"                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:CookieParameter                     ConvertEmptyStringToNull="True|False"                     CookieName="string"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:FormParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     FormField="string"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:Parameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:ProfileParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     PropertyName="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:QueryStringParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     QueryStringField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />                 <asp:SessionParameter                     ConvertEmptyStringToNull="True|False"                     DefaultValue="string"                     Direction="Input|Output|InputOutput|ReturnValue"                     Name="string"                     SessionField="string"                     Size="integer"                     Type="Empty|Object|DBNull|Boolean|Char|SByte| Byte|Int16|UInt16|Int32|UInt32|Int64|UInt64| Single|Double|Decimal|DateTime|String"                 />         </UpdateParameters> </asp:ObjectDataSource>
Represents a business object that provides data to data-bound controls in multitier Web application architectures.
Constructor To be added. Initializes a new instance of the class. 2.0.0.0 Constructor The value of the parameter can be a partially qualified type for code that is located in the Bin or App_Code directory or a fully qualified type name for code that is registered in the global assembly cache. If you use the global assembly cache, you must add the appropriate reference to the assemblies section of the Machine.config or Web.config configuration file. Initializes a new instance of the class with the specified type name and data retrieval method name. The name of the class that the works with. The name of the method or function that the invokes to retrieve data. 2.0.0.0 Property System.ComponentModel.TypeConverter("System.Web.UI.DataSourceCacheDurationConverter, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.ComponentModel.DefaultValue(0) System.Int32 To be added. The control supports data caching. While data is cached, calls to the method retrieve data from the cache rather than from the business object that the works with. When the cache expires, the method retrieves data from the business object, and then caches the data again. The control automatically caches data when the property is set to true and the property is set to a value greater than 0, which indicates the number of seconds that the cache stores data before the cache entry is discarded. A value of 0 indicates an infinitely long cache. The cache is regulated by a combination of the duration and the setting. If the property is set to the value, the caches data on the first call to the method and holds it in memory for, at most, the amount of time that is specified by the property. The data might be released before the duration time, if the memory is needed. The cache is then refreshed during the next call to the method. If the property is set to value, the data source control caches data on the first call to the method, but resets the time window for which it holds the cache on each subsequent call to the method. The cache expires if there is no activity for a time that is equal to the property since the last call to the method. Gets or sets the length of time, in seconds, that the data source control caches data that is retrieved by the property. 2.0.0.0 Property System.ComponentModel.DefaultValue(System.Web.UI.DataSourceCacheExpiry.Absolute) System.Web.UI.DataSourceCacheExpiry To be added. The control supports data caching. While data is cached, calls to the method retrieve data from the cache rather than from the business object that the works with. When the cache expires, the method retrieves data from the business object, and then caches the data again. The control automatically caches data when the property is set to true and the property is set to a value greater than 0, which indicates the number of seconds that the cache stores data before the cache entry is discarded. A value of 0 indicates an infinitely long cache period. The cache is regulated by a combination of the duration and the setting. If the property is set to the value, the caches data on the first call to the method and holds it in memory for, at most, the amount of time that is specified by the property. The data might be released before the duration time, if the memory is needed. The cache is then refreshed during the next call to the method. If the property is set to the value, the data source control caches data on the first call to the method, but resets the time window for which it holds the cache for each subsequent call to the method. The cache expires if there is no activity for a time that is equal to the property since the last call to the method. Gets or sets the cache expiration behavior that, when combined with the duration, describes the behavior of the cache that the data source control uses. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The property can be set to any arbitrary string value. All cache objects are explicitly expired when the key is expired. This allows you to invalidate cache entries that are created by the from your own page code programmatically. The control supports data caching. While data is cached, calls to the method retrieve data from the cache rather than from the business object that the works with. When the cache expires, the method retrieves data from the business object, and then caches the data again. The control automatically caches data when the property is set to true and the property is set to a value greater than 0, which indicates the number of seconds that the cache stores data before the cache entry is discarded. A value of 0 indicates an infinitely long cache. You can set the property to create a dependency between all cache entries that are created by the control and the key. You can expire all the cache entries programmatically at any time by expiring the key. Expire the key by using the method with the current value as the parameter. A unique cache entry is created for every combination of the , , , , and properties. Multiple controls can use the same cache entries in scenarios where they load data using the same type, method, and parameters. Gets or sets a user-defined key dependency that is linked to all data cache objects that are created by the data source control. 2.0.0.0 Property System.ComponentModel.DefaultValue(System.Web.UI.ConflictOptions.OverwriteChanges) System.Web.UI.ConflictOptions To be added. This property determines whether parameters for old and new values are applied to the method specified by the property. For example, if the method that is specified by the property returns a control with the columns Name and Number, and the property is set to the field, parameters are created for Name and Number for the Update method. If the property is set to the value, parameters are created for Name, Number, original_Name, and original_Number. (The exact name of the parameters for the original values depends on the property.) The then determines whether the method that is specified in the property has parameters that match. Concurrency control is a technique that data stores use to control how data is read and changed in the store when multiple clients are accessing and manipulating the same data. For example, one client reads data and presents it to a user, while another client reads the same data and presents it to a different user. If both users update the data and submit it to the data storage, an unexpected result might occur, because both clients might provide different values for the same data. This is considered a conflict. By setting the property to the value, the Update method can then compare the old and new values to the original data source to detect conflicts and handle them as necessary. The property delegates to the property of the object that is associated with the control. Gets or sets a value that determines whether or not just the new values are passed to the Update method or both the old and new values are passed to the Update method. 2.0.0.0 Property System.ComponentModel.DefaultValue(false) System.Boolean To be added. Not converting null to the value can result in errors at run time. Use the property to indicate whether values that are passed to an update, insert, or delete operation are automatically converted from null to the value by the control. Gets or sets a value indicating whether the values that are passed to an update, insert, or delete operation are automatically converted from null to the value by the control. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. Instead of specifying several parameters that are passed to the , , and methods, you can create one object that aggregates several data field values. This one object is passed to the methods, instead of several parameters. The default behavior of an control that is bound to a data-bound control is that the data-bound control creates a object for each parameter in the data source. If the business object has many fields, the resulting method also has many fields. The property allows you to specify a type that has a property for each data field. Then, instead of passing several parameters to the method, the runtime creates one object and sets all of its properties. This one object is added to the parameters collection for the method call. The type that is specified by the property must have a default constructor that has no parameters, so the control can create an instance of the type. The type must also have settable properties that allow the control to populate the object with values that are passed from the data-bound control. The property names on the control are expected to exactly match the parameter names of values that are passed by the data-bound control. When the property is set and the control is associated with a data-bound control, the methods that are specified by the and properties must each have one parameter of the type that is specified in the property. If the property is set to the value, the method that is specified by the property must have one parameter of the type that is specified in the property. If the property is set to the value, the method that is specified by the property must have two parameters of the type that is specified in the property. The first parameter contains the original values; the second parameter contains the new values. The property delegates to the property of the that is associated with the control. Gets or sets the name of a class that the control uses for a parameter in an update, insert, or delete data operation, instead of passing individual values from the data-bound control. 2.0.0.0 Method System.Int32 Before the operation is performed, the method is called to raise the event. You can handle the event to examine the values of the parameters and to perform any preprocessing before a operation. To perform a delete operation, the object uses reflection to create an instance of the object that is identified by the property. It then calls the method that is identified by the property, using any associated properties. If the deletion parameters come from an associated data-bound control, the name of the parameters is created according to the property. After the operation completes, the method is called to raise the event. You can handle the event to examine any return values, output parameters, and exceptions, and to perform any post-processing. The method delegates to the method of the object that is associated with the control.

Data-Bound Controls

When the control is associated with a data-bound control, such as the control, it is not necessary to call the method from page code. The method is invoked directly by the data-bound control instead. For more information about parameter merging, object lifetime, and method resolution, see .
Performs a delete operation by calling the method that is identified by the property with any parameters that are in the collection. A value that represents the number of rows deleted from the underlying data storage, if the property of the is set in the event; otherwise, -1.
2.0.0.0
Event System.Web.UI.WebControls.ObjectDataSourceStatusEventHandler Handle the event to examine the values of a return value or output parameters, or to determine whether an exception was thrown after a operation has completed. The return value, output parameters, and exception handling properties are available from the object that is associated with the event. You can use the property of the object to return the number of rows that were deleted from the method. To do this, set the property. If you return the number of deleted rows from the method that is specified by the property, the value is available from the property of the object. For more information about handling events, see
Consuming Events. Occurs when a operation has completed. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The business object is assumed to delete data one record at a time, rather than in a batch. The property delegates to the property of the object that is associated with the control. Make sure that the parameter names configured for the control in the collection match the column names that are returned by the select method.

Object Lifetime

The method that is identified by the property can be an instance method or a static (Shared in Visual Basic) method. If it is an instance method, the business object is created and destroyed each time the property is called. You can handle the and events to work with the business object before the property is called. You can also handle the event that is raised after the property is called. If the business object implements the interface, the method is called before the object is destroyed. If the method is a static (Shared in Visual Basic) method, the business object is never created and you cannot handle the , , and events.

Parameter Merging

Parameters are added to the collection from three sources: From the data-bound control, at run time. From the DeleteParameters element, declaratively. From the Deleting method, declaratively. First, any parameters that are generated from data-bound controls are added to the collection. For example, if the control is bound to a control that has the columns Name and Number, parameters for Name and Number are added to the collection. The exact name of the parameter depends on the property. The data type of these parameters is string. Next, the parameters that are listed in the DeleteParameters element are added. If a parameter in the DeleteParameters element is found with the same name as a parameter that is already in the collection, the existing parameter is modified to match the parameter that is specified in the DeleteParameters element. Typically, this is used to modify the type of the data in the parameter. Finally, you can programmatically add and remove parameters in the event, which occurs before the method is run. The method is resolved after the parameters are merged. Method resolution is discussed in the next section.

Method Resolution

When the method is called, the data fields from the data-bound control, the parameters that were created declaratively in the DeleteParameters element, and the parameters that were added in the event handler are all merged. (For more information, see the preceding section.) The object then attempts to find a method to call. First, it looks for one or more methods with the name that is specified in the property. If no match is found, an exception is thrown. If a match is found, it then looks for matching parameter names. For example, suppose the type that is specified by the property has two methods named DeleteARecord. One DeleteARecord has one parameter, , and the other DeleteARecord has two parameters, and . If the collection has only one parameter named , the DeleteARecord method with just the parameter is called. The type of the parameter is not checked in resolving the methods. The order of the parameters does not matter. If the property is set, the method is resolved in a different way. The looks for a method with the name that is specified in the property that takes one parameter of the type that is specified in the property. In this case, the name of the parameter does not matter.
Gets or sets the name of the method or function that the control invokes to delete data.
2.0.0.0
Property System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.DefaultValue(null) System.ComponentModel.Editor("System.Web.UI.Design.WebControls.ParameterCollectionEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.ComponentModel.MergableProperty(false) System.Web.UI.WebControls.ParameterCollection To be added. The names and types of the parameters that are contained in the collection must match the names and types of the parameters in the method signature. The parameter names are affected by the property and are case-sensitive. The parameters in the collection depend on the data that is in the data-bound control, the parameters that are specified declaratively, and the parameters that are added programmatically. For more information, see "Parameter Merging" in and Using Parameters with the ObjectDataSource Control. The property retrieves the property that is contained by the object that is associated with the control. For more information about parameter merging, object lifetime, and method resolution, see . Gets the parameters collection that contains the parameters that are used by the method. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceMethodEventHandler Handle the event to perform additional initialization that is specific to your application, to validate the values of parameters, or to change the parameter values before the control performs the delete operation. The parameters are available as an collection that is accessed by the property, which is exposed by the object. You can cancel the delete operation by setting the property of the to true. For more information about handling events, see Consuming Events. Occurs before a operation. 2.0.0.0 Property System.ComponentModel.DefaultValue(false) System.Boolean To be added. The control supports data caching. While data is cached, calls to the method retrieve data from the cache rather than the creating an instance of the business object and calling its data method. When the cache expires, the method retrieves data from the business object, and then caches the data again. The control automatically caches data when the property is set to true and the property is set to a value greater than 0, which indicates the number of seconds that the cache stores data before the cache entry is discarded. A value of 0 indicates an infinitely long cache. Gets or sets a value indicating whether the control has data caching enabled. 2.0.0.0 Property System.ComponentModel.DefaultValue(false) System.Boolean To be added. Paging by the control is handled by setting the , , , and properties of the and defining a select method in the business object with the proper parameters. When the property is set to true, the collection includes two additional parameters for the first row that is requested and the number of rows that are requested. These two parameters are named as defined by the and properties. The Select method should return the requested number of rows, starting at the specified index. Because the data might not divide evenly by the page size, the last page might contain fewer rows. Thus, the number of rows that are requested is actually the maximum number of rows that are returned. When paging is enabled on the associated data-bound control, the data-bound control calls the Select method with the start index and number of rows that are required. Additionally, if the property is set, the data-bound control calls the method before rendering the pager controls. For example, if a control has paging enabled with a page size of 5, and the method that is specified by the property returns 20, only 4 pages are displayed in the pager. The property delegates to the property of the object. Gets or sets a value that indicates whether the data source control supports paging through the set of data that it retrieves. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The control supports filtering data only when the method returns a or object. The syntax that is used for the property is a format string–style expression. The filter expression syntax is the same syntax that is accepted by the property. If you add parameters to the collection, you can also include format string placeholders. For example, include "{0}" in the expression to substitute for parameter values. The placeholders are replaced according to the index of the parameter in the collection. You can include parameters in the property. If the type of the parameter is a string or character type, enclose the parameter in single quotation marks. Quotation marks are not required if the parameter is a numeric type. The collection contains the parameters that are evaluated for the placeholders that are found in the property. The property delegates to the property of the object that is associated with the control. You should validate any filter parameter value that you receive from the client. The runtime simply substitutes the parameter value into the filter expression and applies it to the or object that is returned by the method. If you are using the property as a security measure to limit the number of items that are returned, you must validate the parameter values before the filtering occurs. Gets or sets a filtering expression that is applied when the method that is specified by the property is called. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceFilteringEventHandler Handle the event to perform validation operations on filter parameter values before the control performs a filter operation. You can cancel the selected operation by setting the property of the to true. The event is raised only if the property is set. The event delegates to the event of the that is associated with the control. You should validate any filter parameter value that you receive from the client. The runtime simply substitutes the parameter value into the filter expression and applies it to the or object that is returned by the method. If you are using the property as a security measure to limit the number of items that are returned, you must validate the parameter values before the filtering occurs. For more information about handling events, see Consuming Events. Occurs before a filter operation. 2.0.0.0 Property System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.DefaultValue(null) System.ComponentModel.Editor("System.Web.UI.Design.WebControls.ParameterCollectionEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.ComponentModel.MergableProperty(false) System.Web.UI.WebControls.ParameterCollection To be added. The control supports filtering data only when the method returns a or object. The syntax that is used for the is a format string–style expression. The filter expression syntax is the same syntax that is accepted by the property. If you add parameters to the collection, you can also include format string placeholders. For example, include "{0}" in the expression to substitute for parameter values. The placeholders are replaced according to the index of the parameter in the collection. You can include parameters in the property. If the parameter is a string or character type, enclose the parameter in single quotation marks. Quotation marks are not required if the parameter is a numeric type. The property retrieves the property that is contained by the object that is associated with the control. Gets a collection of parameters that are associated with any parameter placeholders in the string. 2.0.0.0 Method System.Web.UI.DataSourceView The control supports only one data source view. As with all data source view objects, the that is associated with the data source control defines its capabilities, performs all the work that is necessary to retrieve data from the underlying data storage, and performs operations such as sorting, inserting, deleting, and updating. The method is intended to be called by data-bound controls, not by page code. Retrieves the named data source view that is associated with the data source control. The named DefaultView that is associated with the . The name of the view to retrieve. Because the supports only one view, is ignored. 2.0.0.0 Method System.Collections.ICollection The control supports only one view, named DefaultView, on its underlying data. The method returns a single-element collection of this one view name. The method is intended to be called by data-bound controls, not by page code. Retrieves a collection of names representing the list of view objects that are associated with the object. An that contains the names of the views associated with the . 2.0.0.0 Method System.Int32 Before the operation is performed, the method is called to raise the event. You can handle the event to examine the values of the parameters and to perform any preprocessing before an operation. To perform an insert operation, the object uses reflection to create an instance of the object that is identified by the property. It then calls the method that is identified by the property, using any associated properties. After the operation completes, the method is called to raise the event. You can handle the event to examine any return values, output parameters, and exceptions, and to perform any post-processing. The method delegates to the method of the that is associated with the control. For more information about parameter merging, object lifetime, and method resolution, see .

Data-Bound Controls

When the object is associated with a data-bound control, such as the control, it is not necessary to call the method from page code. The method is invoked directly by the data-bound control instead.
Performs an insert operation by calling the method that is identified by the property and any parameters in the collection. A value that represents the number of rows inserted into the underlying data storage.
2.0.0.0
Event System.Web.UI.WebControls.ObjectDataSourceStatusEventHandler Handle the event to examine the values of a return value or output parameters, or to determine whether an exception was thrown after an operation has completed. The return value, output parameters, and exception handling properties are available from the object that is associated with the event. For more information about handling events, see Consuming Events. Occurs when an operation has completed. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceMethodEventHandler Handle the event to perform additional initialization that is specific to your application, to validate the values of parameters, or to change the parameter values before the control performs the insert operation. The parameters are available as an collection that is accessed by the property, which is exposed by the object. For more information about handling events, see Consuming Events. Occurs before an operation. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The business object is assumed to insert data one record at a time, rather than in a batch. The property delegates to the property of the object that is associated with the object.

Object Lifetime

The method that is identified by the property can be an instance method or a static (Shared in Visual Basic) method. If it is an instance method, the business object is created and destroyed each time the method specified by the property is called. You can handle the and events to work with the business object before the property is called. You can also handle the event that is raised after the method that is specified by the property is called. If the business object implements the interface, the method is called before the object is destroyed. If the method is static (Shared in Visual Basic), the business object is never created and you cannot handle the , , and events.

Parameter Merging

Parameters are added to the collection from three sources: From the data-bound control, at run time. From the InsertParameters element, declaratively. From the Inserting method, programmatically. First, any parameters that are generated from data-bound controls are added to the collection. For example, if the control is bound to a control that has the columns Name and Number, the parameters for Name and Number are added to the collection. The data type of these parameters is string. Next, the parameters that are listed in the InsertParameters element are added. If a parameter in the InsertParameters element is found with the same name as a parameter that is already in the collection, the existing parameter is modified to match the parameter that is specified in the InsertParameters element. Typically, this is used to modify the type of the data in the parameter. Finally, you can programmatically add and remove parameters in the event, which occurs before the method is run. The method is resolved after the parameters are merged. Method resolution is discussed in the next section. You should validate any parameter value that you receive from the client. The runtime simply substitutes the parameter value into the property.

Method Resolution

When the method is called, the data fields from the data-bound control, the parameters that were created declaratively in the InsertParameters element, and the parameters that were added in the event handler are all merged. (For more information, see the preceding section.) The object then attempts to find a method to call. First, it looks for one or more methods with the name that is specified in the property. If no match is found, an exception is thrown. If a match is found, it then looks for matching parameter names. For example, suppose a type that is specified by the property has two methods named InsertARecord. One InsertARecord has one parameter, , and the other InsertARecord has two parameters, and . If the collection has only one parameter named , the InsertARecord method with just the parameter is called. The type of the parameter is not checked in resolving the methods. The order of the parameters does not matter. If the property is set, the method is resolved in a different way. The looks for a method with the name that is specified in the property that takes one parameter of the type that is specified in the property. In this case, the name of the parameter does not matter.
Gets or sets the name of the method or function that the control invokes to insert data.
2.0.0.0
Property System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.DefaultValue(null) System.ComponentModel.Editor("System.Web.UI.Design.WebControls.ParameterCollectionEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.ComponentModel.MergableProperty(false) System.Web.UI.WebControls.ParameterCollection To be added. The names and types of the parameters that are contained in the collection must match the names and types of the parameters that are in the property signature. The parameter names are case sensitive. When working with data-bound controls that supply parameters, such as the and controls, the control automatically merges any parameters that are explicitly specified in the collection with the parameters that are provided by the data-bound control. This is important because data-bound controls always supply their parameters as types, and if the method signature includes numeric or date types, you must explicitly include a parameter in the collection with the correct type. Otherwise, the control attempts to cast the parameters according to the type that is defined by the parameters in the collection. For more information, see Using Parameters with the ObjectDataSource Control. The property retrieves the property that is contained by the that is associated with the control. For more information about parameter merging, object lifetime, and method resolution, see . Gets the parameters collection that contains the parameters that are used by the property. 2.0.0.0 Method System.Void This method is used primarily by the .NET Framework infrastructure and is not intended to be used directly from your code. However, control developers can override this method to specify how a custom server control restores its view state. For more information, see ASP.NET State Management Overview. The method is used to load the previously saved view state of the control. Loads the previously saved view state of the control. An object that contains the saved view state values for the control. 2.0.0.0 Property System.ComponentModel.DefaultValue("maximumRows") System.String To be added. The property is used to support data source paging. For information about how paging is supported by the control, see . The property delegates to the property of the object that is associated with the control. Gets or sets the name of the business object data retrieval method parameter that is used to indicate the number of records to retrieve for data source paging support. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceObjectEventHandler Handle the event to call other methods on the business object, set properties, or perform other initialization that is specific to the business object before the object calls the business object data method to perform a data operation. A reference to the object is accessed by the property, which is exposed by the object. If the method that is identified to perform the data operation is static (Shared in Visual Basic), the and events are never raised. For more information about handling events, see Consuming Events. Occurs after the object that is identified by the property is created. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceObjectEventHandler If the method that is identified to perform the data operation is static (Shared in Visual Basic), the and events are never raised. The control automatically calls the default constructor of a business object to create an instance of it using reflection. Handle the event to explicitly call another constructor, and set the instance of the object that results to the property of the associated object. For more information about handling events, see Consuming Events. Occurs before the object that is identified by the property is created. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceDisposingEventHandler The event is always raised before the instance of the business object is discarded. If the business object implements the interface, the method is called after this event is raised. Handle the event to call other methods on the object, set properties, or perform clean-up that is specific to the object before the object is destroyed. A reference to the object is accessed by the property, which is exposed by the object. When you use a control with a LINQ to SQL class, you must cancel the disposing of the data-context class in an handler for the event. This step is necessary because LINQ to SQL supports deferred execution, whereas the control tries to dispose the data context after the Select operation. For more information about how to handle events, see Consuming Events. Occurs before the object that is identified by the property is discarded. 2.0.0.0 Property System.ComponentModel.DefaultValue("{0}") System.String To be added. The value of the property is applied to primary keys only, such as those that are identified with the DataKeyNames property of a data-bound control, or in delete and update scenarios where the property is set to the value, and the set of original values are passed to the corresponding data method. The following are two common scenarios where you might change the property: You might want to change the property to differentiate between old and new values in updates. When the property is set to the value, parameters for both the original and new values are added to the collection. Without the formatting string, two parameters with the same name would be created for each data field. By changing the name of the original value parameter, you can compare the data to the original data source to detect conflicts and compare key values. Some visual designers implement a particular naming scheme for original values and keys. The property delegates to the property of the object that is associated with the control. Gets or sets a format string to apply to the names of the parameters for original values that are passed to the Delete or Update methods. 2.0.0.0 Method 2.0.0.0 System.Void Raising an event invokes the event handler through a delegate. For more information, see Consuming Events. The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. Adds a event handler to the page that contains the control. An that contains event data. Method System.Object To be added. Saves the state of the control. Returns the server control's current view state; otherwise, returns null, if there is no view state associated with the control. 2.0.0.0 Method System.Collections.IEnumerable The specified method might have any method signature, but it must return or be derived from one of the types listed in the following table for the control to call it successfully. Return type Action The is returned by the method. A is created by using the and returned by the method. The is returned by the method. The first of the is extracted and a is created and returned by the method. The object is wrapped in a one-element collection and returned by the method. The method that is identified by the property can be an instance method or a static (Shared in Visual Basic) method. If it is an instance method, the business object is created and destroyed each time the method that is specified by the property is called, except that the same instance is used to call the method that is specified by the property and the method that is specified by the property. The method returns an interface. However, to enable caching and filtering scenarios, the return value must be a object. While the class does not implement the interface, the control automatically extracts the default control, which implements the . Before the operation is performed, the method is called to raise the event. You can handle the event to examine the values of the parameters and to perform any preprocessing before a operation. To perform a data retrieval operation, the object uses reflection to create an instance of the object that is identified by the property. It then calls the method that is identified by the property, using any associated properties. After the operation completes, the method is called to raise the event. You can handle the event to examine any return values, output parameters, and exceptions, and to perform any post-processing. If the property returns a , , or object and caching is enabled, the retrieves data from and saves data to the cache during the operation. The cache is created, discarded, or refreshed based on the caching behavior that is specified by the combination of the and properties. If the property returns a or object, and a property has been specified, it is evaluated with any supplied properties and the resulting filter is applied to the list of data during the operation. The method delegates to the method of the that is associated with the control. For more information about parameter merging, object lifetime, and method resolution, see .

Data-Bound Controls

When the control is associated with a data-bound control, such as the control, it is not necessary to call the method from page code. The method is invoked directly by the data-bound control instead.
Retrieves data from the underlying data storage by calling the method that is identified by the property with the parameters in the collection. An list of data rows.
2.0.0.0
Property System.ComponentModel.DefaultValue("") System.String To be added. The property identifies a business object method that is used to retrieve a total row count, to support data source paging. The property is evaluated only if the property is set to true. The property delegates to the property of the object that is associated with the control. For information about how paging is supported by the control, see . Gets or sets the name of the method or function that the control invokes to retrieve a row count. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceStatusEventHandler Handle the event to examine the values of a return value or output parameters, or to determine whether an exception was thrown after a operation has completed. The return value, output parameters, and exception handling properties are available from the object that is associated with the event. For more information about handling events, see Consuming Events. Occurs when a operation has completed. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceSelectingEventHandler Handle the event to perform additional initialization that is specific to your application, to validate the values of parameters, or to change the parameter values before the control performs the data retrieval operation. The parameters are available as an collection that is accessed by the property, which is exposed by the object. This event can be fired twice for a single call to the method, if the property is set. The property of the object is used to determine if select was called to retrieve data or retrieve the count. For more information about handling events, see Consuming Events. Occurs before a operation. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The specified method can have any method signature, but it must return one of the types shown in the following table for the control to call it successfully. Return type Action The is returned by the method. A is created using the and returned by the method. A is returned by the method. The first of the is extracted, and a is created and returned by the method. The object is wrapped in a one-element collection and returned by the method. The property delegates to the property of the object that is associated with the control. When you use the class to delete or update data, make sure that the parameter names configured for the control in the collection or collection match the column names that are returned by the select method.

Object Lifetime

The method that is identified by the property can be an instance method or a static (Shared in Visual Basic) method. If it is an instance method, the business object is created and destroyed each time the method that is specified by the property is called. You can handle the and events to work with the business object before the method that is specified by the property is called. You can also handle the event that is raised after the method that is specified by the property is called. If the business object implements the interface, the method is called before the object is destroyed. If the method is static (Shared in Visual Basic), the business object is never created and you cannot handle the , , and events.

Parameter Merging

Parameters are added to the collection from these sources: Declaratively from the SelectParameters element. Programmatically from the Selecting method. First, the parameters listed in the SelectParameters element are added. Second, parameters are programmatically added and removed in the event, which occurs before the method is run. The method is resolved after the parameters are merged. Method resolution is discussed in the next section. You should validate any parameter value that you receive from the client. The runtime simply substitutes the parameter value into the property.

Method Resolution

When the method is called, the data fields from the data-bound control, the parameters that were created declaratively in the SelectParameters element, and the parameters that were added in the event handler are all merged. (For more information, see the preceding section.) The control then attempts to find a method to call. First, it looks for one or more methods with the name that is specified in the property. If no match is found, an exception is thrown. If a match is found, it then looks for matching parameter names. For example, suppose a type that is specified by the property has two methods named SelectARecord. One SelectARecord has one parameter, , and the other SelectARecord has two parameters, and . If the collection has only one parameter named , the SelectARecord method with just the parameter is called. The type of the parameter is not checked in resolving the methods. The order of the parameters does not matter. If the property is set, the method is resolved in a different way. The looks for a method with the name that is specified in the property that takes one parameter of the type that is specified in the property. In this case, the name of the parameter does not matter.
Gets or sets the name of the method or function that the control invokes to retrieve data.
2.0.0.0
Property System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.DefaultValue(null) System.ComponentModel.Editor("System.Web.UI.Design.WebControls.ParameterCollectionEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.ComponentModel.MergableProperty(false) System.Web.UI.WebControls.ParameterCollection To be added. The property gets the property of the object that is associated with the control. You add parameters to the collection declaratively by using the SelectParameters element or programmatically in the handler for the event. At run time, parameters listed in the SelectParameters element are added to the collection first. Parameters in the collection are then added or removed by the handler for the event. The event is raised before the method is run. Before the method is run, the names and types of the parameters that are contained in the collection must match the signature of the method that is specified by the property. For example, if a select method named GetEmployeesByStateAndAge takes a string and an integer as parameters, the collection must contain two parameters. The first parameter must resolve to a string and the second parameter must resolve to an integer. Both parameters can be specified in markup in the SelectParameters element. Alternatively, they can be can be added in the event handler, or one parameter can be added in markup and the other one can be added programmatically. For more information, see Using Parameters with the ObjectDataSource Control and the property. In the code for the event handler or in the method that is specified by the property, make sure that you validate any parameter value that is received from the client. Gets a collection of parameters that are used by the method specified by the property. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The property is used to support data source sorting. When a property is set on the object and passed to the method, the value identifies the parameter name of the business object method according to which the data is sorted. If the is associated with a data-bound control, the values that are passed to this parameter take the form of comma-separated field values followed by "ASC" or "DESC". For example, the value for an ascending sort on Name would be "Name ASC". The property delegates to the property of the object that is associated with the control. Gets or sets the name of the business object that the parameter used to specify a sort expression for data source sorting support. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The control supports an optional expiration policy that is based on the object for the data cache (the service must be configured for the database server). SQL Server supports two mechanisms for cache invalidation: polling and notification. Each mechanism has a different syntax for the object. The supports only polling. The string is used to create a object that is passed to the constructor before the method is executed. The string identifies databases and tables according to the same format that is used by the @ Page directive, where the first part of the string is a connection string to a SQL Server database, followed by a colon delimiter, and finally the name of the database table (for example, "connectionstring1:table1"). If the property depends on more than one table, the connection string and table name pairs are separated by semicolons (for example, "connectionstring1:table1";connectionstring2:table2"). To support notification, you must write the cache logic in the implementation of your property and handle the construction of the object in your code. Gets or sets a semicolon-delimited string that indicates which databases and tables to use for the Microsoft SQL Server cache dependency. 2.0.0.0 Property System.ComponentModel.DefaultValue("startRowIndex") System.String To be added. The property is used to support data source paging. For information about how paging is supported by the control, see . The property delegates to the property of the object that is associated with the control. Gets or sets the name of the data retrieval method parameter that is used to indicate the value of the identifier of the first record to retrieve for data source paging support. 2.0.0.0 Method System.Void The method is overridden to mark the starting point to begin tracking and saving changes to the control as part of the view state for the object. Tracks view-state changes to the control so that they can be stored in the object. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. To create an instance of the object that the control binds to, the control uses reflection to load the type that is identified by the type name at run time. Therefore, the value of the property can be a partially qualified type for code that is located in the Bin or App_Code directories or a fully qualified type name for code that is registered in the global assembly cache. If you use the global assembly cache, you must add the appropriate reference to the assemblies section of the Machine.config or Web.config file. The type must have a default constructor, unless you handle the event to create an instance of it yourself. An instance of the type is created for each call to the , , , and methods, if the methods on the type are member methods. An instance is not created if the methods are static (Shared in Visual Basic). If the type implements the interface, the method is called before the object is destroyed. Gets or sets the name of the class that the object represents. 2.0.0.0 Method System.Int32 The business object is assumed to update data one record at a time, rather than in a batch. Before the operation is performed, the method is called to raise the event. You can handle the event to examine the values of the parameters and to perform any preprocessing before an operation. To perform an update operation, the object uses reflection to create an instance of the object that is identified by the property. It then calls the method that is identified by the property, using any associated properties. After the operation completes, the method is called to raise the event. You can handle the event to examine any return values, output parameters, and exceptions, and to perform any post-processing. The method delegates to the method of the that is associated with the control. For more information about parameter merging, object lifetime, and method resolution, see . You should validate any parameter value that you receive from the client. The runtime simply substitutes the parameter value into the property.

Data-Bound Controls

When the control is associated with a data-bound control, such as the control, it is not necessary to call the method from page code. The method is invoked directly by the data-bound control instead.
Performs an update operation by calling the method that is identified by the property and any parameters that are in the collection. A value that represents the number of rows updated in the underlying data storage.
2.0.0.0
Event System.Web.UI.WebControls.ObjectDataSourceStatusEventHandler Handle the event to examine the values of a return value or output parameters, or to determine whether an exception was thrown after an operation has completed. The return value, output parameters, and exception handling properties are available from the object that is associated with the event. For more information about handling events, see Consuming Events. Occurs when an operation has completed. 2.0.0.0 Property System.ComponentModel.DefaultValue("") System.String To be added. The control assumes that the method that is identified by the property performs updates one at a time, rather than in a batch. The property delegates to the property of the object that is associated with the control. Make sure that the parameter names configured for the control in the collection match the column names that are returned by the select method.

Object Lifetime

The method that is identified by the property can be an instance method or a static (Shared in Visual Basic) method. If it is an instance method, the business object is created and destroyed each time the method that is specified by the property is called. You can handle the and events to work with the business object before the method that is specified by the property is called. You can also handle the event that is raised after the method that is specified by the property is called. If the business object implements the interface, the method is called before the object is destroyed. If the method is static (Shared in Visual Basic), the business object is never created and you cannot handle the , , and events.

Parameter Merging

Parameters are added to the collection from three sources: From the data-bound control, at run time. From the UpdateParameters element, declaratively. From the event handler, programmatically. First, any parameters that are generated from data-bound controls are added to the collection. For example, if the control is bound to a control that has the columns Name and Number, the parameters for Name and Number are added to the collection. The exact name of the parameter depends on the property. The data type of these parameters is string. Next, the parameters that are listed in the UpdateParameters element are added. If a parameter in the UpdateParameters element is found with the same name as a parameter that is already in the collection, the existing parameter is modified to match the parameter that is specified in the UpdateParameters element. Typically, this is used to modify the type of the data in the parameter. Finally, you can programmatically add and remove parameters in the event, which occurs before the method is run. The method is resolved after the parameters are merged. Method resolution is discussed in the next section. You should validate any parameter value that you receive from the client. The runtime simply substitutes the parameter value into the property.

Method Resolution

When the method is called, the data fields from the data-bound control, the parameters that were created declaratively in the UpdateParameters element, and the parameters that were added in the event handler are all merged. (For more information, see the preceding section.) The control then attempts to find a method to call. First, it looks for one or more methods with the name that is specified in the property. If no match is found, an exception is thrown. If a match is found, it then looks for matching parameter names. For example, suppose a type that is specified by the property has two methods named UpdateARecord. One UpdateARecord has one parameter, , and the other UpdateARecord has two parameters, and . If the collection has only one parameter named , the UpdateARecord method with just the parameter is called. The type of the parameter is not checked in resolving the methods. The order of the parameters does not matter. If the property is set, the method is resolved in a different way. The looks for a method with the name that is specified in the property that takes one parameter of the type that is specified in the property. In this case, the name of the parameter does not matter.
Gets or sets the name of the method or function that the control invokes to update data.
2.0.0.0
Property System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.DefaultValue(null) System.ComponentModel.Editor("System.Web.UI.Design.WebControls.ParameterCollectionEditor, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") System.ComponentModel.MergableProperty(false) System.Web.UI.WebControls.ParameterCollection To be added. The names and types of the parameters that are contained in the collection must match the names and types of the parameters in the method signature. The parameter names are affected by the property and are case-sensitive. The parameters in the collection depend on the data in the data-bound control, the parameters that are specified declaratively, and the parameters that are added programmatically. For more information, see the "Parameter Merging" section in and Using Parameters with the ObjectDataSource Control. The property retrieves the property that is contained by the object that is associated with the control. For more information about parameter merging, object lifetime, and method resolution, see . You should validate any parameter value that you receive from the client. The runtime simply substitutes the parameter value into the property. Gets the parameters collection that contains the parameters that are used by the method that is specified by the property. 2.0.0.0 Event System.Web.UI.WebControls.ObjectDataSourceMethodEventHandler Handle the event to perform additional initialization that is specific to your application, to validate the values of parameters, or to change the parameter values before the control performs the update operation. The parameters are available as an collection that is accessed by the property, which is exposed by the object. For more information about handling events, see Consuming Events. Occurs before an operation. 2.0.0.0