Any CallbackHandler derived 'service' can be easily accessed via REST calls simply by providing the proper QueryString or POST variables to the server. The handler makes the remote method call and returns a JSON formatted string in response.
The easiest way to access the service is with AjaxMethodCallback control on Page which simply exposes each of the service's methods as Methods on a proxy object. You can simply call Proxy.MyMethod(parm1, parm2, CallbackHandler, ErrorHandler).
However you can also call these services directly with any HTTP tool using plain REST functionality.
ajaxJson("ClientCallbacks.ashx?Method=CallbackWithPost", $.param( { Name: "Rick", Entered: new Date(), Value: 10}), function(result) {alert("Message from Server:\r\n" + result) }, function(error) { alert(error.message); }, { noPostEncoding: true } );
This passes the raw post data (created with $.param from the object map) to the CallbackWithPost() method on the server. The server can then read the values with Request.Form["Name"], Request.Form["Date"] for example. You can really specify any kind of data you like here. Note the final parameter of true which indicates using raw POST data as opposed to a JSON object.
You can also do this with any other HTTP client as long as you can produce a JSON encoded string. So you can also use $.post() or $.ajax() for example but you'll have to handle the encoding and decoding of JSON manually.
ajaxJson("StockService.ashx?Method=GetStockQuote", "MSFT", function(result) {alert("MSFT Last Price: " + result.LastPrice); }, function(error) {alert(error.message);} );
The parameter passed here is a string which is ajaxJson converts into a JSON string that is sent to the server. The result returned is an object/value that the method returns.
To handle the server call implement a handler method like this:
[CallbackMethod] public StockQuote GetStockQuote(string symbol) { StockService service = new StockService(); return service.GetStockQuote(symbol); // returns a StockQuoteObject }
You can pass exactly one parameter to the server, but the parameter can be a complex object. If necessary you can create a parameter object that contains multiple values. For example imagine this type:
public class Person { public string Name = null; public int Value = 0; public DateTime Date = DateTime.MinValue; }
and a callback method with this signature:
[CallbackMethod] public string TestMethod2(Person person) { return person.Name + " " + person.Value.ToString() + " " + person.Date; }
To pass this value from the client:
ajaxJson("TestService.ashx?Method=TestMethod2", { Name:"Rick", Value:10, Date: new Date() }, function(result) {alert("Message from Server:\r\n" + result) }, function(error) { alert(error.message); } );
The type doesn't have to match exactly - it'll read only matching properties from the JSON value so if you pass only Name (ie. { Name:"Rick" } ) and leave out the other object properties/fields the code still works.
Note that I used ajaxJson from ww.jquery.js here, but it's not required. Any HTTP client that can post JSON data can do this.
This mechanism relies on regular POST or Querystring values that define the method to call and the parameters to pass. The POST/querystring values for the callbacks are simple and only the following variables need to be supplied:
CallbackMethod
The method in the service handler to call.
CallbackParmCount
The number of JSON parameters passed
Parm1..n
0 or more parameters to be passed to the method called. Note the method must support these parameters. Parameters passed must be JSON encoded in the POST buffer and must be passed in the same order as the method signature. Values can be simple types or complex types as long as the server's input type matches the object signature.
GET Example:
http://site.com/app/jsonHandler.ashx?CallbackParmCount=2&CallbackMethod=HelloWorld&Parm1="Rick Strahl"&Parm2={"x":10,"y":20}
Note that all parameters are JSON formatted (the quotes around a string for example), so you can pass any JSON value to the server as long as it is calling a method that has a signature that expects that signature. Objects are matched based on properties/fields that are updated from matching properties.
Again, if you are using ww.jquery or the server controls the AjaxMethodCallback control and client class are the easiest way to automate this process. If you want to find out more detail on how to encode the content you can check out the AjaxMethodCallback client class for more details.