Documentation for: ASP.NET Ajax Version 1.0

This documentation is for a previous version. For the current released version, see the ASP.NET Ajax documentation on MSDN.

 

 

 

 

 

 

 

Skip Navigation Links.
Tutorials
Sample ASP.NET AJAX Application
ASP.NET AJAX and JavaScript
Extending JavaScript with ASP.NET AJAX
Creating Custom Client Script in ASP.NET AJAX
Dynamically Assigning ASP.NET AJAX Script References
Globalizing a Date by Using Client Script
Embedding a JavaScript File as a Resource in an Assembly
Embedding Localized Resources for a JavaScript File
Adding Localized Resources to a JavaScript File
Creating Custom Client Events
The UpdatePanel Control
Introduction to the UpdatePanel Control
Creating a Simple ASP.NET Page with Multiple UpdatePanel Controls
Using the UpdatePanel Control with Data-Bound Controls
Using the UpdatePanel Control with Master Pages
Using the UpdatePanel Control with User Controls
Using the UpdatePanel Control with a Web Service
Customizing Error Handling for UpdatePanel Controls
Animating UpdatePanel Controls
Canceling an Asynchronous Postback
Giving Precedence to a Specific Asynchronous Postback
Working with PageRequestManager Events
The UpdateProgress Control
Introduction to the UpdateProgress Control
Programming UpdateProgress Controls in Client Script
The Timer Control
Introduction to the Timer Control
Using the Timer Control with Multiple UpdatePanel Controls
ASP.NET Application Services
Using Forms Authentication
Using Profile Information
Web Services
Exposing Web Services to Client Script
Calling Web Services from Client Script
ASP.NET AJAX Extensibility
Creating Custom ASP.NET AJAX Non-Visual Client Components
Creating Custom ASP.NET AJAX Client Controls
Creating an Extender Control
Adding Client Capabilities to a Web Server Control
Creating a Client Component Class Using the Prototype Model
Defining Custom Component Properties and Raising PropertyChanged Events
Releasing Component Resources

Calling Web Services from Client Script in ASP.NET AJAX

Introduction

This topic explains how to use to call a Web service from ECMAScript (JavaScript). To enable your application to call ASP.NET AJAX Web services by using client script, the server asynchronous communication layer automatically generates JavaScript proxy classes. A proxy class is generated for each Web service for which an <asp:ServiceReference> element is included under the <asp:ScriptManager> control in the page. 

For more information, see Exposing Web Services to Client Script.

To call a method of the Web service, you call the corresponding method of the generated JavaScript proxy class. The proxy class in turn communicates with the Web service.

Calling Web Service Methods

Calling a Web service method from script is asynchronous. To get a return value or to determine when the request has returned, you must provide a succeeded callback function. The callback function is invoked when the request has finished successfully, and it contains the return value (if any) from the Web method call. You can also provide a failed callback function to handle errors. Additionally, you can pass user context information to use in the callback functions.

The following example shows how to make the following types of Web service calls:

  • Calling a Web service that has no return value.

  • Calling a Web service that returns a value.

  • Calling a Web service method that takes parameters.

  • Calling a Web service method by using the HTTP GET verb.

  • Calling a Web service method that returns an XmlDocument object.

Specifying Callback Functions as Default Properties

In the previous examples, calls to Web service methods are made by using the proxy class. Information about the succeeded callback function, the failed callback function, and the user context is passed by using additional parameters in the call.

As an alternative, you can specify a succeeded callback function, a failed callback function, and user context as default properties for the class. Your script can then invoke the Web service methods of the proxy class without passing these values as parameters in the call. This simplifies the syntax of calling Web service methods.

The following example shows how to set default properties on the Web service proxy class, and then call a Web service method.

MyNameSpace.MyService.set_defaultSucceededCallback(SucceededCallback);
MyNameSpace.MyService.set_defaultFailedCallback(FailedCallback);
MyNameSpace.MyService.set_defaultUserContext("my context");
MyNameSpace.MyService.myServiceMethod(param1, param2);

Setting Callback Functions as Properties of Proxy Class Instances

You can also create instances of the generated proxy class. In that case, you can specify a succeeded callback function, a failed callback function, and user context as default properties for each instance. As with calling the generated proxy class, you can then use the proxy class instances to call Web service methods without passing these values as parameters in the call.

You typically create proxy-class instances when you want to make multiple calls to methods of the Web service and use different default property values for each instance. For example, you can specify different callback functions for each instance. By using different callback functions, you can process the returned data in different ways based on your application needs and on the nature of the returned data.

The following example shows how to create an instance of a proxy class, set its default properties, and call the related Web service method:

var myServiceProxy = new MyNameSpace.MyService();
myServiceProxy.set_defaultSucceededCallback(SuccededCallback);
myServiceProxy.set_defaultFailedCallback(FailedCallback);
MyNameSpce.MyService.set_defaultUserContext("my context");
myServiceProxy.myServiceMethod(param1, param2); 

For more information, see Generated Proxy Classes.

Handling Errors in Web Service Method Calls

The following example shows how to handle errors that are raised by Web service methods. In order to catch errors, you must provide a failed callback function that accepts a single parameter. This parameter will contain the error object sent by the Web service.

The following example show how to provide a failed callback function that is called if an error occurs during a Web service method call.

Calling a Single Callback Function from Multiple Web Service Methods

You can provide a single succeeded callback function that is invoked from multiple Web service method calls. In order for the function to distinguish between callers, you can pass user context to it, or you can test for the name of the calling method. The user context and the calling method name are both available in the callback function, as shown in the following example:

Passing and Returning Complex Types

If the Web service method returns a complex type, the succeeded callback function receives a return value in the form of a JavaScript object that corresponds to the server type. The following example shows a Web service method that returns a complex type.

The following example shows how to call Web service methods that have parameters that correspond to complex types. Proxy classes for the types will be automatically generated. This enables client script to create instances of the type to pass as parameters to the method call.

Passing Parameters Typed as Generics or Arrays

A Web service method might support parameters or a return value that are typed as generics or arrays of lists of type T. In that case, ASP.NET AJAX automatically generates proxy classes for the type T for use with client script. However if a generic type takes more than one type argument, such as Dictionary<string, <T>>, ASP.NET AJAX does not generate proxy classes for the types.

For ASP.NET AJAX to generate a proxy class for the type T, the Web service class that uses the type must be qualified with the GenerateScriptTypeAttribute attribute for the type T.

The following example shows how to call a Web service method from client script when the parameters are typed as generics or arrays.

Passing Parameters Typed as Enumerators

An enumerator type can be accessed by using the automatically generated proxy class.

note

You cannot access enumerators by using instances of the generated proxy class.

The following example shows how to call a Web service method from client script when the parameters are typed as enumerators.