ARI .NET Ajax Programming Example Code

ARI Examples

Here I will demonstrate how to use ARI so you can see the clean syntax and just how quicky you can enable an entire website using this library. You can also download the software which include a website loaded with example code. For each of the examples below, I will give a brief description of what you are looking at, and include both the JavaScript code as well as the server-side code in C#. Note that in these exmaples, a single error callback function called err_PageCallback is used for brevity. This will suffice for many applications, but you can have a different error callback for each of your calls.

Demo calling C# method that has a return type of void

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of void. Notice that the callback is still called, but there is nothing being passed to the callback.

function exec_ReturnVoid() {
    SampleMethods.ReturnVoid(cb_ReturnVoid, onARIError);
}

function cb_ReturnVoid() {
    alert("ReturnVoid executed and returned nothing.");
}

public void ReturnVoid()
{
    // whatever...
}

Demo calling C# method that has a return type of boolean

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of bool, which means that the parameter passed to the success callback function is a boolean value as well.

function exec_ReturnBoolean() {
    SampleMethods.ReturnBoolean(cb_ReturnBoolean, err_PageCallback);
}

function cb_ReturnBoolean(rv) {
    alert("ReturnBoolean executed and returned:\r\r" + rv);
}

public bool ReturnBoolean()
{
    return true;
}

Demo calling C# method that has a return type of string

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of string, which means that the parameter passed to the success callback function is a string value as well.

function exec_ReturnString() {
    SampleMethods.ReturnString(cb_ReturnString, err_PageCallback);
}

function cb_ReturnString(rv) {
    alert("ReturnString executed and returned:\r\r" + rv);
}

public string ReturnString()
{
    return "This is a string.";
}

Demo calling C# method that has a return type of integer

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of int, which means that the parameter passed to the success callback function is a number value with no decimal places

function exec_ReturnInt() {
    SampleMethods.ReturnInt(cb_ReturnInt, err_PageCallback);
}

function cb_ReturnInt(rv) {
    alert("ReturnInt executed and returned:\r\r" + rv);
}

public int ReturnInt()
{
    Random rand = new Random();
    return rand.Next();
}

Demo calling C# method that has a return type of float

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of float, which means that the parameter passed to the success callback function is a number value that may have decimal places, if the actual return value from the server had decimal places.

function exec_ReturnFloat() {
    SampleMethods.ReturnFloat(cb_ReturnFloat, err_PageCallback);
}

function cb_ReturnFloat(rv) {
    alert("ReturnFloat executed and returned:\r\r" + rv);
}

public float ReturnFloat()
{
    return 101.399f;
}

Demo calling C# method that has a return type of DateTime

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of DateTime, which means that the parameter passed to the success callback function is a JavaScript Date object.

function exec_ReturnDateTime() {
    SampleMethods.ReturnDateTime(cb_ReturnDateTime, err_PageCallback);
}

function cb_ReturnDateTime(rv) {
    alert("ReturnDateTime executed and returned:\r\r" + rv);
}

public DateTime ReturnDateTime()
{
    return DateTime.Now;
}

Demo calling C# method that has a return type of Hashtable

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of Hashtable, which means that the parameter passed to the success callback function is a JavaScript object. Notice how nicely a C# hastable maps to a JavaScript object, with the keys being properties and the values being - duh - values.

function exec_ReturnHashtable() {
    SampleMethods.ReturnHashtable(cb_ReturnHashtable, err_PageCallback);
}

function cb_ReturnHashtable(rv) {
    var data = "Name: " + rv["Name"];
    data += "\r" + "Occupation: " + rv["Occupation"];
    data += "\r" + "Age: " + rv["Age"];
    data += "\r" + "Salary: " + rv["Salary"];
    alert("ReturnHashtable executed and returned: \r\r" + data);
}

public Hashtable ReturnHashtable()
{
    Hashtable ht = new Hashtable();
    ht["Name"] = "George Washington";
    ht["Occupation"] = "Retired U.S. president";
    ht["Age"] = 53;
    ht["Salary"] = 2750.24m;
    return ht;
}

Demo calling C# method that has a return type of ArrayList

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of ArrayList, which means that the parameter passed to the success callback function is a JavaScript Array type.

function exec_ReturnArrayList() {
    SampleMethods.ReturnArrayList(cb_ReturnArrayList, err_PageCallback);
}

function cb_ReturnArrayList(rv) {
    alert("ReturnArrayList executed and returned:\r\r" + rv);
}

public ArrayList ReturnArrayList()
{
    ArrayList list = new ArrayList();
    list.Add("Item 1");
    list.Add("Item 2");
    list.Add("Item 3");
    list.Add("Item 4");
    return list;
}

Demo calling C# method that has a return type of DataTable

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of DataTable, which means that the parameter passed to the success callback function is an array of JavaScript objects. This actually works quite nicely, with each row mapping to a JavaScript object. The column names in the row are the object properties, and the actual data values are the values. In this example I created the DataTable manually, but in practice, you would most likely be returning a DataTable that you got from the database.

function exec_ReturnDataTable() {
    SampleMethods.ReturnDataTable(cb_DataTable, err_PageCallback);
}

function cb_DataTable(rv) {
    var data = "";
    for (var i=0; i<rv.length; ++i)
    {
        data += "\r\rName: " + rv[i]["Name"];
        data += "\r" + "Age: " + rv[i]["Age"];
        data += "\r" + "Address: " + rv[i]["Address"];
        data += "\r" + "Salary: " + rv[i]["Salary"];
    }
    alert("DataTable executed and returned: " + data);
}

public DataTable ReturnDataTable()
{
    DataTable table = new DataTable();
    table.Columns.Add("Name", typeof(string));
    table.Columns.Add("Age", typeof(int));
    table.Columns.Add("Address", typeof(string));
    table.Columns.Add("Salary", typeof(decimal));
    table.Rows.Add("Tom Jefferson", 57, "1600 Pennsylvania Ave.", 3051.23m);
    table.Rows.Add("John Smith", 35, "14 Main Street", 4200.19m);
    table.Rows.Add("Mary Benkins", 41, "11 Deer Run Road", 151383.40m);
    table.Rows.Add("Marcia Brady", 49, "3983 Television Drive", 429141.54m);
    return table;
}

Demo calling C# method that has a return type of binary. (Base64 encoded.)

Description
View JavaScript
View C# Method

In this example, the C# server-side method has a return type of byte[] (binary data). On the server side, ARI converts this to a base 64 string and sends it back to the client callback as a base 64 string. In this example, as is the case in most, I am simply demonstrating that data transmission and data conversion has taken place successfully, and not really doing anything with the returned data. By the way, to generate binary data, I just took an image file and read it into a byte stream.

function exec_ReturnBinary() {
    SampleMethods.ReturnBinary(cb_ReturnBinary, err_PageCallback);
}

function cb_ReturnBinary(rv) {
    alert("ReturnBinary executed and returned:\r\r" + rv);
}

public byte[] ReturnBinary()
{
    string dir = HttpContext.Current.Server.MapPath("~/");
    DirectoryInfo di = Directory.GetParent(dir);
    string file = di.FullName + @"\images\dog.png";
    byte[] binaryData = ImageReader.ReadImageFileFromDisk(file);
    return binaryData;
}

Demo calling STATIC C# method that has a return type of string

Description
View JavaScript
View C# Method

In this example, the C# server-side method is a static that has a return type of string, which means that the parameter passed to the success callback function is a string value as well. This is just to demonstrate that ARI can execute static methods as well as instance methods in the App_Code tree. Note that the methods invoked are limited to those that have public scope.

function exec_ReturnStringFromStaticMethod() {
    SampleMethods.ReturnStringFromStaticMethod(cb_ReturnStringFromStaticMethod, err_PageCallback);
}

function cb_ReturnStringFromStaticMethod(rv) {
    alert("ReturnStringFromStaticMethod executed and returned:\r\r" + rv);
}

public static string ReturnStringFromStaticMethod()
{
    return "This is a string from a static method.";
}

Demo calling various overloaded C# methods

Description
View JavaScript
View C# Method

Note that the only difference between the four server side methods is the parameter types they take. This demonstrates that using .NET reflection, ARI dynamically figures out which of the server side methods to call. Refer to the discussion on narrowing and widening coercion on the ARI main page for an understanding on how method arguments can be "promoted". This code, as well as most of the other examples on this page, are included in the download.

function exec_DemoMethodOverload1() {
    SampleMethods.DemoMethodOverload(cb_DemoMethodOverload, err_PageCallback, 10, 32);        
}

function exec_DemoMethodOverload2() {
    SampleMethods.DemoMethodOverload(cb_DemoMethodOverload, err_PageCallback, 40, 98.6);        
}

function exec_DemoMethodOverload3() {
    SampleMethods.DemoMethodOverload(cb_DemoMethodOverload, err_PageCallback, 101.3, 456.876);        
}

function exec_DemoMethodOverload4() {
    SampleMethods.DemoMethodOverload(cb_DemoMethodOverload, err_PageCallback, "some string", 99);        
}

function cb_DemoMethodOverload(rv) {
    alert("DemoMethodOverload executed and returned:\r\r" + rv);
}

public string DemoMethodOverload(int a, int b)
{
    return "Called: DemoMethodOverload(int a, int b)";
}

public string DemoMethodOverload(int a, float b)
{
    return "Called: DemoMethodOverload(int a, float b)";
}

public string DemoMethodOverload(float a, float b)
{
    return "Called: DemoMethodOverload(float a, float b)";
}

public string DemoMethodOverload(string a, int b)
{
    return "Called: DemoMethodOverload(string a, int b)";
}

Demo calling C# method that takes an Array as a parameter

Description
View JavaScript
View C# Method

In this example, the C# server-side method requires an argument of type ArrayList. This means that the parameter passed from the JavaScript call should be an Array.

function exec_SendArrayParam() {
    var a = new Array();
    a.push(1);
    a.push(2);
    a.push(3);
    a.push(4);
    a.push(5);
    a.push(6);
    a.push(7);
    SampleMethods.SendArrayParam(cb_SendArrayParam, err_PageCallback, a);
}

function cb_SendArrayParam(rv) {
    alert("SendArrayParam executed and returned:\r\r" + rv);
}

public string SendArrayParam(ArrayList list)
{
    return string.Format("Your array had {0} items.", list.Count);
}

Demo calling C# method that takes a javascript object as a parameter

Description
View JavaScript
View C# Method

In this example, the C# server-side method requires an argument of type Hashtable. This means that the parameter passed from the JavaScript call should be an object. ARI will convert this to a HashTable using the properties as keys and values as values.

function exec_SendHashtableParam() {
    var obj = new Object();
    obj["name"] = "John";
    obj["phone"] = "555-1212";
    obj["age"] = 35;
    SampleMethods.SendHashtableParam(cb_SendHashtableParam, err_PageCallback, obj);
}

function cb_SendHashtableParam(rv) {
    alert("SendHashtableParam executed and returned:\r\r" + rv);
}

public string SendHashtableParam(Hashtable hash)
{
    return string.Format("Your Hashtable had {0} entries.", hash.Count);
}

Demo calling C# method that takes an array of javascript objects as a parameter

Description
View JavaScript
View C# Method

In this example, the C# server-side method requires an argument of type ArrayList. This means that the parameter passed from the JavaScript call should be an Array. This is similar to another example, except that I am showing the flexibility in ARI to be able to nest objects to and from the server. Instead of a simple Array being passed to the web server, we are passing an array of objects. Conceptually, this can be considered a DataTable or a 2-dimensional array.

function exec_SendObjectArrayParam() {
    var obj1 = new Object();
    obj1["name"] = "John";
    obj1["phone"] = "555-1212";

    var obj2 = new Object();
    obj2["name"] = "Mark";
    obj2["phone"] = "555-0000";

    var obj3 = new Object();
    obj3["name"] = "Matt";
    obj3["phone"] = "555-9999";
    
    var table = new Array();
    table.push(obj1);
    table.push(obj2);
    table.push(obj3);            

    SampleMethods.SendObjectArrayParam(cb_SendObjectArrayParam, 
        err_PageCallback, table);
}

function cb_SendObjectArrayParam(rv) {
    alert("SendObjectArrayParam executed and returned:\r\r" + rv);
}

public string SendObjectArrayParam(ArrayList table)
{
    return string.Format("Your object array contained {0} structures.", 
        table.Count);
}

Demo calling C# method that throws an exception

Description
View JavaScript
View C# Method

In this example, I demonstrate what happens when/if the C# server-side method throws an exception. The exception is gracefully caught by the ARI server side ServerAgent, who then passes back the error message back to the fault handler specified as the second parameter in the client side call. In this example, it is the error callback err_PageCallback. Of course, in this example, the success callback, called cb_DemoMethodException would never be executed since our server method always causes an exception to be thrown.

function exec_DemoMethodException() {
    SampleMethods.DemoMethodException(cb_DemoMethodException, 
        err_PageCallback);
}

function cb_DemoMethodException(rv) {
    alert("DemoMethodException executed and returned:\r\r" + rv);
}

function err_PageCallback(e) {
    alert("Error: " + e);
}

public string DemoMethodException()
{
    // here I purposely cause an exception to be thrown...
    ArrayList list = new ArrayList();
    list.Add(5);
    // will cause an out of bounds exception
    list[200] = 15;
    return "Some return value";
}

Demo calling C# method takes nested hashtable as a parameter

Description
View JavaScript
View C# Method

In this example, the C# server-side method requires an argument of type Hashtable. This means that the parameter passed from the JavaScript call should be of type object. I kind of went crazy here, just nesting things and sending all kinds of things to the server. I did this to demonstrate the recursive serialization and deserialization I wrote into ARI. This feature is one of the most powerful things about ARI. Very often I may need to send (or receive) more than type of data structure to/from the server. What I usually do in that case is to build a self-describing message. What I mean by that is I send a Hashtable whose keys describe the associated data value. Very handy! (see the very next example for how to do this when the data is coming from the server rather than going to the server.)

function exec_SendComplexType() {
    var a = new Array();
    a.push(1);
    a.push(2);
    a.push(3);
    a.push(4);
    
    var b = new Array();
    b.push(55);
    b.push(66);
    b.push(77);
    b.push(88);

    var obj1 = new Object();
    obj1["name"] = "John";
    obj1["phone"] = "555-1212";
    obj1["INNER KEY 1"] = b;
    
    var param = new Object();
    param["KEY 1"] = a;
    param["KEY 2"] = obj1;

    SampleMethods.SendComplexType(cb_SendComplexType, 
        err_PageCallback, param);
}

function cb_SendComplexType(rv) {
    alert("SendComplexType executed and returned:\r\r" + rv);
}

public string SendComplexType(Hashtable hash)
{
    ArrayList list = (ArrayList)hash["KEY 1"];
    Hashtable innerHash = (Hashtable)hash["KEY 2"];
    ArrayList innerList = (ArrayList)innerHash["INNER KEY 1"];
    return "Data received successfully. Place a breakpoint " + 
        "in SampleMethods.SendComplexType to see nesting.";
}

Demo calling C# method that returns hashtable with nested data structures

Description
View JavaScript
View C# Method

In this example, the C# server-side method is returning a Hashtable which itself contains a DataTable, an an ArrayList. As illustrated in the previous example, this is to show the recursive data serialization and deserialization capabilities of ARI.

function exec_ReturnComplexType() {
    SampleMethods.ReturnComplexType(cb_ReturnComplexType, 
        err_PageCallback);
}

function cb_ReturnComplexType(rv) {
    var str = rv["KEY 1"];
    var list = rv["KEY 3"];
    var dt = rv["KEY 2"];

    var data = "\rHere is the simple string portion: " + str;
    data += "\r\rHere is the array portion: " + list;
    data += "\r\rHere is the DataTable portion: ";
    for (var i=0; i<dt.length; ++i)
    {
        data += "\r\rName: " + dt[i]["Name"];
        data += "\r" + "Age: " + dt[i]["Age"];
        data += "\r" + "Address: " + dt[i]["Address"];
        data += "\r" + "Salary: " + dt[i]["Salary"];
    }
    alert("ReturnComplexType executed and returned:\r\r" + data);
}

public Hashtable ReturnComplexType()
{
    DataTable dt = ReturnDataTable();
    ArrayList list = ReturnArrayList();
    Hashtable ht = new Hashtable();
    ht.Add("KEY 1", "This is a string item");
    ht.Add("KEY 2", dt);
    ht.Add("KEY 3", list);
    return ht;
}

Demonstrates how ARI can execute 100 asynchronous calls

Description
View JavaScript
View C# Method

I put this example here just to demonstrate that ARI can handle multiple requests. Of course, some browsers limit the number of concurrent calls oustanding at any one time. ARI's JavaScript proxy code queues up the server calls and fires them off as fast as possible. You really can't see much in the example code for this methos, so I suggest you download ARI and run it on your machine. On my development box, this code executes the 100 round trip calls very quickly - almost instantaneously.

var theDiv = null;
function exec_DemoMultipleCalls() {
    theDiv = document.getElementById("outDiv");
    theDiv.innerHTML = "<br />";
    
    for (var i=0; i<100; ++i)
    {
        SampleMethods.DemoMultipleCalls(cb_DemoMultipleCalls, err_PageCallback, i, i);
    }    
}

function cb_DemoMultipleCalls(rv) {
    theDiv.innerHTML += (rv.toString() + ", ");
}

public int DemoMultipleCalls(int a, int b)
{
    return a + b;
}