ASP.NET AJAX and ADO.NET Data Services

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

You can interact with an ADO.NET data service from any application that can send an HTTP request to an ADO.NET data service URI and that can process the response in the format that is returned from the data service. The ASP.NET AJAX library provides the Sys.Data.AdoNetServiceProxy client script class for simplifying the interaction between an ASP.NET AJAX application and an ADO.NET data service. By using this class, you can create Web applications that interact with data through a data service on the Web site, and that can update the Web page without a full postback to the Web server.

You can also use an AdoNetDataContext instance with a DataView object. You can enable read and write capabilities and change tracking by setting the dataProvider property of the DataView to an AdoNetDataContext instance.

This topic contains information about how to create an instance of the AdoNetServiceProxy script class in an ASP.NET AJAX Web site, and how to use the script class to query or modify data through the data service.

Prerequisites

In order to use the AdoNetServiceProxy class or the AdoNetDataContext class, you must add references to the MicrosoftAjaxAdoNet.js and the MicrosoftAjaxTemplates.js ASP.NET AJAX libraries.

To use these classes in an ASP.NET Web page, a Web application must target , and a Web page should include appropriate script references, as shown in the following example:

<asp:ScriptManager ID="sm" runat="server">
  <Scripts>
    <asp:ScriptReference Name="MicrosoftAjaxTemplates.js" />
    <asp:ScriptReference Name="MicrosoftAjaxAdoNet.js" />
  </Scripts>
</asp:ScriptManager>

To use ASP.NET AJAX templates in an HTML page or in an MVC view, you must obtain the static script files for the ASP.NET AJAX Framework, such as the latest ASP.NET AJAX Preview release. For more information, see the ASP.NET AJAX Web site.

Your page should then include script elements that reference the appropriate script libraries as shown in the following example:

<script type="text/javascript" src="MicrosoftAjax.debug.js"></script>
<script type="text/javascript" src="MicrosoftAjaxTemplates.debug.js"></script>
<script type="text/javascript" src="MicrosoftAjaxAdoNet.debug.js"></script>

ADO.NET Data Services

The ADO.NET Data Services framework lets you create and access data services on the Web. The services use well-known formats to represent the data, such as JSON and XML. Data is made available across the Web in the style of a representational state transfer (REST) resource collection that is addressable by using URIs. Clients can interact with the resources by using HTTP verbs such as GET, PUT, POST, and DELETE. The ADO.NET Data Services framework can expose any data source (database data, XML documents, Web services, and so on) as a REST service. Client applications, such as those that use the ASP.NET AJAX client library for ADO.NET Data Services, can then access the data that is made available by the services. For more information, see ADO.NET Data Services Framework.

Connecting to a Data Service Using AJAX

You use the AdoNetServiceProxy script class to execute data operations of a data service. When you create an instance of the AdoNetServiceProxy class, you provide the relative URI of the data service that contains the data that you want to retrieve, as shown in the following example:

var exampleService = 
    new Sys.Data.AdoNetServiceProxy("/northwind.svc");

Querying Data

After you create an instance of the AdoNetServiceProxy class, you can call the query method to retrieve data from the data service. The following example shows how to return all the records in the Customers table.

exampleService.query("/Customers", cbSuccess, cbFailure); 

The AdoNetServiceProxy class creates a URI for querying the data service by combining the value that you set in the class constructor with the value for the query parameter in the query method. The previous example combined with the class constructor example creates the URI with the following value:

/northwind.svc/Customers

The call to the query method references cbSuccess as the succeeded callback function, and cbFailure as the failed callback function. You add these callback functions to evaluate the results of the query.

You can also use the query method to specify conditions. The following example shows how to request sales orders with the shipped date of 1998 or later for the customer who is represented by the key "ALFKI":

exampleService.query("/Customers('ALFKI')/Orders?$filter=ShippedDate ge '1998-01-01'", cbSuccess, cbFailure);

Deferred Property Values

When a property in the returned data contains a large amount of data, the property value might be excluded from the results in order to avoid problems with bandwidth or CPU processing. The process of getting the data for the property is deferred until you explicitly request it by calling the fetchDeferredProperty method. A property that has been deferred will contain a property named __deferred that indicates whether the property value was deferred. For more information, see Deferred Content.

The following example shows you how to use the fetchDeferredProperty method to request the data for a property that was excluded from the original results:

if (selectedItem.ProductSubcategory.__deferred) {
  exampleServiceProxy.fetchDeferredProperty(
    selectedItem, 
    "ProductSubcategory",
    succeededFetchDeferredCallback,
    failedFetchDeferredCallback
  );
}

Modifying Data

The AdoNetServiceProxy class provides the following methods that you can call in order to modify data through a data service:

• insert

• update

• remove

• createActionSequence

You call the insert, update, or remove methods to perform a single data operation in the request. When you call these methods, the operation request is sent immediately to the data service.

The following example shows an insert operation that adds a new record in the Categories table with the value of "Decorations" for the CategoryName field.

var newCategory = {"CategoryName":"Decorations"};
exampleService.insert(newCategory,"/Categories");

The newCategory variable represents the data as a JavaScript object.

You use the createActionSequence method when you want to execute multiple data modification actions as a batch. The createActionSequence method returns an instance of the Sys.Data.AdoNetActionSequence class. You add data modification steps to the AdoNetActionSequence object and execute those steps by calling the execute method of the AdoNetActionSequence object.

For an example of how to execute a sequence of actions, see How to: Execute a Sequence of Actions Through a Data Service Using AJAX.

Data Classes for ADO.NET Data Services

The ADO.NET data classes let you add code and UI in a data source to a Web page that interacts with an ADO.NET data service. For instance, you can set the AdoNetDataContext instance as the data source for the ASP.NET AJAX DataView client control. This lets you provide data-driven UI that shows data from the service and enables updates to be submitted to the service.

The following table lists the ADO.NET data classes for ASP.NET AJAX.

Related Topics

See Also

Concepts

ASP.NET AJAX Roadmap

Other Resources

ADO.NET Data Services Framework

Data Service Quickstart