Performing Insert Operations

This article is relevant to entity models that utilize the deprecated Visual Studio integration of Telerik Data Access. The current documentation of the Data Access framework is available here.

With the OpenAccessLinqDataSource control, you can create ASP.NET Web pages that enable users to insert, update, and delete data. You don't have to write any additional code, because the OpenAccessLinqDataSource control dynamically performs these operations. To let users modify data, you can enable insert, update, or delete operations on the OpenAccessLinqDataSource control. You can then connect the control to a data-bound control that lets the users insert, update, and delete data, such as the RadGrid control.

This topic describes how to enable the OpenAccessLinqDataSource control to automatically handle insert operations. It also describes how to set properties programmatically before an insert operation is performed. Finally, the topic makes an overview of the Inserting/Inserted events, exposed by the OpenAccessLinqDataSource control.

How to: Enable Automatic Inserts

To enable a data-bound control to automatically perform insert operations, you must do the following:

1. Connect the OpenAccessLinqDataSource control to a domain model and specify the target table.

2. On the second page of the wizard (i.e. the Configure Data Selection page), you need to ensure that the following conditions are met:

   1. You need to select all (*) properties for the specified entity. When you check the Select All (*) option, full entities are returned instead of results that contain individual properties. (*) is the default selection, i.e. all of the properties will be used. If you choose specific properties, you won't get an entity object back. Instead, you will get a projection, which cannot be change-tracked, and therefore cannot be updated. In this case automatic inserts, updates, and deletes are not allowed.

      

   2. Switch to the Advanced tab page and check the Enable Automatic Inserts option.

      

   3. You should not have any GroupBy operations.

3. Click Finish to close the wizard.

If you have already created an OpenAccessLinqDataSource control on your web page, you don't need to re-configure it:

1. Select the control in design time.

2. By using the Smart Tag panel, check the Enable insert option.

   

   Note that, if you haven't used the Select All (*) option or you have grouping, then the Enable delete/insert/update options in the Smart Tag panel will not be available.

The following example shows the markup for part of an ASP.NET Web page that contains an OpenAccessLinqDataSource. The control is configured to enable the user to display and insert data in a table named Categories.

<telerik:OpenAccessLinqDataSource
   ID="OpenAccessLinqDataSource1"
   runat="server"
   ContextTypeName="OpenAccessLinqDataSourceDemo.EntitiesModel"
   ResourceSetName="Categories"
   EntityTypeName=""
   EnableInsert="True" />

How to: Add Default Values for Insert Data

By default, you don't need to add parameters for insert data. The data-bound control passes its values to the OpenAccessLinqDataSource control, and the data source control uses these values to set the corresponding properties. However, you have the option to provide default values for inserting data in the InsertParameters collection. These values are used only in the case when no values are entered for the corresponding properties.

Consider the following example. You have a data-bound control that is bound to a table named Categories with columns CategoryId, CategoryName and ImageFileName. InsertParameter is specified for the ImageFileName property. If no value is specified for the ImageFileName property during the insert, then the specified default value is used; otherwise, the default value is ignored.

<telerik:OpenAccessLinqDataSource
   ID="OpenAccessLinqDataSource1"
   runat="server"
   ContextTypeName="OpenAccessLinqDataSourceDemo.EntitiesModel"
   ResourceSetName="Categories"
   EntityTypeName=""
   EnableInsert="True">

   <InsertParameters>
       <asp:Parameter Name="ImageFileName" DefaultValue="Demo.png" />
   </InsertParameters>

</telerik:OpenAccessLinqDataSource>

Using the Inserting/Inserted Events

The Inserting event occurs before an insert operation. You could handle the Inserting event to validate the object to be inserted, to change a value before the insert operation, or to cancel the insert operation. The OpenAccessLinqDataSourceInsertEventArgs object passed to the event handler for this event contains the new object to insert in the database. The OpenAccessLinqDataSourceInsertEventArgs object also exposes information about validation errors. For example, a validation error occurs if a value to be inserted does not match the type of the property in the domain class. You can retrieve the validation exceptions via the Exception property and take appropriate actions. For example:

protected void OpenAccessLinqDataSource_Inserting(object sender, 
    Telerik.OpenAccess.Web.OpenAccessLinqDataSourceInsertEventArgs e)
{
   if (e.Exception != null)
   {
       foreach (KeyValuePair<string, Exception> innerException in
               e.Exception.InnerExceptions)
       {
           // Process the exception
       }
       e.ExceptionHandled = true;
   }
}

Protected Sub OpenAccessLinqDataSource_Inserting(ByVal sender As Object,_
    ByVal e As Telerik.OpenAccess.Web.OpenAccessLinqDataSourceInsertEventArgs) _
        Handles OpenAccessLinqDataSource.Inserting
 If e.Exception IsNot Nothing Then
  For Each innerException As KeyValuePair(Of String, Exception) In e.Exception.InnerExceptions
   ' Process the exception
  Next innerException
  e.ExceptionHandled = True
 End If
End Sub

The Inserting event allows you to modify data before the insert operation. The following example demonstrates how to do this. Note that you need to access the NewObject property. It is of type object and you have to cast it to the type that represents the table.

protected void OpenAccessLinqDataSource_Inserting(object sender, 
Telerik.OpenAccess.Web.OpenAccessLinqDataSourceInsertEventArgs e)
{
   Category newCategory = e.NewObject as Category;
   if (newCategory != null)
   {
       newCategory.ImageFileName = "Demo.png";
   }
}

Protected Sub OpenAccessLinqDataSource_Inserting(ByVal sender As Object,_
    ByVal e As Telerik.OpenAccess.Web.OpenAccessLinqDataSourceInsertEventArgs) _
        Handles OpenAccessLinqDataSource.Inserting
 Dim newCategory As Category = TryCast(e.NewObject, Category)
 If newCategory IsNot Nothing Then
  newCategory.ImageFileName = "Demo.png"
 End If
End Sub

The OpenAccessLinqDataSourceInsertEventArgs derives from CancelEventArgs, i.e. it is a cancelable event. You can cancel the insert operation by setting the Cancel property to True.

protected void OpenAccessLinqDataSource_Inserting(object sender, 
Telerik.OpenAccess.Web.OpenAccessLinqDataSourceInsertEventArgs e)
{
   e.Cancel = true;
}

Protected Sub OpenAccessLinqDataSource_Inserting(ByVal sender As Object,_
    ByVal e As Telerik.OpenAccess.Web.OpenAccessLinqDataSourceInsertEventArgs) _
        Handles OpenAccessLinqDataSource.Inserting
 e.Cancel = True
End Sub

The Inserted event occurs when an insert operation has finished. You could handle the Inserted event to catch any backend exceptions from the insert operation or to examine the values after the insert operation has finished. To access the new object, you need to examine the Result property of the OpenAccessLinqDataSourceStatusEventArgs class.