Programming Microsoft ASP.NET 4 - Dino Esposito [466]
The JavaScript proxy class is named according to different rules for Web and WCF services. For Web services, the proxy gets the exact fully qualified name of the class behind the .asmx endpoint. For WCF services, the name of the proxy class is determined by the concatenation of the Namespace and Name properties specified in the ServiceContract attribute you’re targeting. Note, therefore, that when you call a WCF service method you’re actually calling a method defined on a contract. To invoke a WCF service, it’s the contract that matters, not the class that implements it. In fact, the same service class can implement multiple contracts.
Using the Proxy
After you have the JavaScript proxy, invoking the Web or WCF service is nearly the same thing. The proxy object comes as a singleton and exposes the same set of contracted methods you have on the original service. The communication model is asynchronous and requires you to specify at least a callback function to use in case of successful execution. Here’s an example:
// Async call of method GetQuotes with a callback
Samples.Services.FinanceInfoService.GetQuotes(symbols, onDataAvailable);
The code can refer to a Web service as well as a WCF service. If it refers to a Web service, the Web service class is named Samples.Services.FinanceInfoService; if it refers to a WCF service, the namespace of the service contract might be Samples.Services and the name of the contract might be FinanceInfoService. The preceding code snippet invokes the method GetQuotes.
In addition to the regular list of parameters for the service method, each proxy method can take up to three extra parameters. The first extra parameter is mandatory and represents the callback to invoke if the method execution is successful. The second and third optional parameters indicate, respectively, the callback to use in case of failure and a state object to pass to both callbacks. In the code snippet just shown, the onDataAvailable parameter refers to a JavaScript callback to call only if the method executes successfully.
The signature of the success and failure callbacks is similar, but the internal format of the results parameter can change quite a bit. Here’s the callback signature:
function method(results, context, methodName)
Table 20-9 provides more details about the various arguments.
Table 20-9. Arguments for a JavaScript Proxy Callback Function
Argument
Description
results
Indicates the return value from the method in the case of success. In the case of failure, a JavaScript Error object mimics the exception that occurred on the server during the execution of the method.
context
The state object passed to the callback.
methodName
The name of the service method that was invoked.
The JavaScript proxy exposes a number of properties and methods for you to configure. The list is presented in Table 20-10.
Table 20-10. Static Properties on a JavaScript Proxy Class
Property
Description
path
Gets and sets the URL of the underlying Web or WCF service.
timeout
Gets and sets the duration (in seconds) before the method call times out.
defaultSucceededCallback
Gets and sets the default JavaScript callback function to invoke for any successful call to a method.
defaultFailedCallback
Gets and sets the default JavaScript callback function, if any, to invoke for a failed or timed-out call.
defaultUserContext
Gets and sets the default JavaScript state object, if any, to be passed to success and failure callbacks.
If you set a “default succeeded” callback, you don’t have to specify a “succeeded” callback in any successive call as long as the desired callback function is the same. The same holds true for the failed callback and the user context object. The user context object