Calling Web Services from Client Script in ASP.NET AJAX
For more information, see Exposing Web Services to Client Script.
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.
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();
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
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.
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.