Using the West Wind Web Toolkit to set up AJAX and REST Services
- by Rick Strahl
I frequently get questions about which option to use for creating AJAX and REST backends for ASP.NET applications. There are many solutions out there to do this actually, but when I have a choice - not surprisingly - I fall back to my own tools in the West Wind West Wind Web Toolkit. I've talked a bunch about the 'in-the-box' solutions in the past so for a change in this post I'll talk about the tools that I use in my own and customer applications to handle AJAX and REST based access to service resources using the West Wind West Wind Web Toolkit. Let me preface this by saying that I like things to be easy. Yes flexible is very important as well but not at the expense of over-complexity. The goal I've had with my tools is make it drop dead easy, with good performance while providing the core features that I'm after, which are: Easy AJAX/JSON Callbacks Ability to return any kind of non JSON content (string, stream, byte[], images) Ability to work with both XML and JSON interchangeably for input/output Access endpoints via POST data, RPC JSON calls, GET QueryString values or Routing interface Easy to use generic JavaScript client to make RPC calls (same syntax, just what you need) Ability to create clean URLS with Routing Ability to use standard ASP.NET HTTP Stack for HTTP semantics It's all about options! In this post I'll demonstrate most of these features (except XML) in a few simple and short samples which you can download. So let's take a look and see how you can build an AJAX callback solution with the West Wind Web Toolkit. Installing the Toolkit Assemblies The easiest and leanest way of using the Toolkit in your Web project is to grab it via NuGet: West Wind Web and AJAX Utilities (Westwind.Web) and drop it into the project by right clicking in your Project and choosing Manage NuGet Packages from anywhere in the Project. When done you end up with your project looking like this: What just happened? Nuget added two assemblies - Westwind.Web and Westwind.Utilities and the client ww.jquery.js library. It also added a couple of references into web.config: The default namespaces so they can be accessed in pages/views and a ScriptCompressionModule that the toolkit optionally uses to compress script resources served from within the assembly (namely ww.jquery.js and optionally jquery.js). Creating a new Service The West Wind Web Toolkit supports several ways of creating and accessing AJAX services, but for this post I'll stick to the lower level approach that works from any plain HTML page or of course MVC, WebForms, WebPages. There's also a WebForms specific control that makes this even easier but I'll leave that for another post. So, to create a new standalone AJAX/REST service we can create a new HttpHandler in the new project either as a pure class based handler or as a generic .ASHX handler. Both work equally well, but generic handlers don't require any web.config configuration so I'll use that here. In the root of the project add a Generic Handler. I'm going to call this one StockService.ashx. Once the handler has been created, edit the code and remove all of the handler body code. Then change the base class to CallbackHandler and add methods that have a [CallbackMethod] attribute. Here's the modified base handler implementation now looks like with an added HelloWorld method: using System;
using Westwind.Web;
namespace WestWindWebAjax
{
/// <summary>
/// Handler implements CallbackHandler to provide REST/AJAX services
/// </summary>
public class SampleService : CallbackHandler
{
[CallbackMethod]
public string HelloWorld(string name)
{
return "Hello " + name + ". Time is: " + DateTime.Now.ToString();
}
}
}
Notice that the class inherits from CallbackHandler and that the HelloWorld service method is marked up with [CallbackMethod]. We're done here. Services
Urlbased Syntax
Once you compile, the 'service' is live can respond to requests. All CallbackHandlers support input in GET and POST formats, and can return results as JSON or XML. To check our fancy HelloWorld method we can now access the service like this:
http://localhost/WestWindWebAjax/StockService.ashx?Method=HelloWorld&name=Rick
which produces a default JSON response - in this case a string (wrapped in quotes as it's JSON):
(note by default JSON will be downloaded by most browsers not displayed - various options are available to view JSON right in the browser)
If I want to return the same data as XML I can tack on a &format=xml at the end of the querystring which produces:
<string>Hello Rick. Time is: 11/1/2011 12:11:13 PM</string>
Cleaner URLs with Routing Syntax
If you want cleaner URLs for each operation you can also configure custom routes on a per URL basis similar to the way that WCF REST does. To do this you need to add a new RouteHandler to your application's startup code in global.asax.cs one for each CallbackHandler based service you create:
protected void Application_Start(object sender, EventArgs e)
{
CallbackHandlerRouteHandler.RegisterRoutes<StockService>(RouteTable.Routes);
}
With this code in place you can now add RouteUrl properties to any of your service methods. For the HelloWorld method that doesn't make a ton of sense but here is what a routed clean URL might look like in definition:
[CallbackMethod(RouteUrl="stocks/HelloWorld/{name}")]
public string HelloWorld(string name)
{
return "Hello " + name + ". Time is: " + DateTime.Now.ToString();
}
The same URL I previously used now becomes a bit shorter and more readable with:
http://localhost/WestWindWebAjax/HelloWorld/Rick
It's an easy way to create cleaner URLs and still get the same functionality.
Calling the Service with $.getJSON()
Since the result produced is JSON you can now easily consume this data using jQuery's getJSON method. First we need a couple of scripts - jquery.js and ww.jquery.js in the page:
<!DOCTYPE html>
<html>
<head>
<link href="Css/Westwind.css" rel="stylesheet" type="text/css" />
<script src="scripts/jquery.min.js" type="text/javascript"></script>
<script src="scripts/ww.jquery.min.js" type="text/javascript"></script>
</head>
<body>
Next let's add a small HelloWorld example form (what else) that has a single textbox to type a name, a button and a div tag to receive the result:
<fieldset>
<legend>Hello World</legend>
Please enter a name:
<input type="text" name="txtHello" id="txtHello" value="" />
<input type="button" id="btnSayHello" value="Say Hello (POST)" />
<input type="button" id="btnSayHelloGet" value="Say Hello (GET)" />
<div id="divHelloMessage" class="errordisplay"
style="display:none;width: 450px;" >
</div>
</fieldset>
Then to call the HelloWorld method a little jQuery is used to hook the document startup and the button click followed by the $.getJSON call to retrieve the data from the server.
<script type="text/javascript">
$(document).ready(function () {
$("#btnSayHelloGet").click(function () {
$.getJSON("SampleService.ashx",
{ Method: "HelloWorld", name: $("#txtHello").val() },
function (result) {
$("#divHelloMessage")
.text(result)
.fadeIn(1000);
});
});</script>
.getJSON() expects a full URL to the endpoint of our service, which is the ASHX file. We can either provide a full URL (SampleService.ashx?Method=HelloWorld&name=Rick) or we can just provide the base URL and an object that encodes the query string parameters for us using an object map that has a property that matches each parameter for the server method. We can also use the clean URL routing syntax, but using the object parameter encoding actually is safer as the parameters will get properly encoded by jQuery.
The result returned is whatever the result on the server method is - in this case a string. The string is applied to the divHelloMessage element and we're done. Obviously this is a trivial example, but it demonstrates the basics of getting a JSON response back to the browser.
AJAX Post Syntax - using ajaxCallMethod()
The previous example allows you basic control over the data that you send to the server via querystring parameters. This works OK for simple values like short strings, numbers and boolean values, but doesn't really work if you need to pass something more complex like an object or an array back up to the server. To handle traditional RPC type messaging where the idea is to map server side functions and results to a client side invokation, POST operations can be used.
The easiest way to use this functionality is to use ww.jquery.js and the ajaxCallMethod() function. ww.jquery wraps jQuery's AJAX functions and knows implicitly how to call a CallbackServer method with parameters and parse the result.
Let's look at another simple example that posts a simple value but returns something more interesting. Let's start with the service method:
[CallbackMethod(RouteUrl="stocks/{symbol}")]
public StockQuote GetStockQuote(string symbol)
{
Response.Cache.SetExpires(DateTime.UtcNow.Add(new TimeSpan(0, 2, 0)));
StockServer server = new StockServer();
var quote = server.GetStockQuote(symbol);
if (quote == null)
throw new ApplicationException("Invalid Symbol passed.");
return quote;
}
This sample utilizes a small StockServer helper class (included in the sample) that downloads a stock quote from Yahoo's financial site via plain HTTP GET requests and formats it into a StockQuote object. Lets create a small HTML block that lets us query for the quote and display it:
<fieldset>
<legend>Single Stock Quote</legend>
Please enter a stock symbol:
<input type="text" name="txtSymbol" id="txtSymbol" value="msft" />
<input type="button" id="btnStockQuote" value="Get Quote" />
<div id="divStockDisplay" class="errordisplay" style="display:none; width: 450px;">
<div class="label-left">Company:</div>
<div id="stockCompany"></div>
<div class="label-left">Last Price:</div>
<div id="stockLastPrice"></div>
<div class="label-left">Quote Time:</div>
<div id="stockQuoteTime"></div>
</div>
</fieldset>
The final result looks something like this:
Let's hook up the button handler to fire the request and fill in the data as shown:
$("#btnStockQuote").click(function () {
ajaxCallMethod("SampleService.ashx", "GetStockQuote",
[$("#txtSymbol").val()],
function (quote) {
$("#divStockDisplay").show().fadeIn(1000);
$("#stockCompany").text(quote.Company + " (" + quote.Symbol + ")");
$("#stockLastPrice").text(quote.LastPrice);
$("#stockQuoteTime").text(quote.LastQuoteTime.formatDate("MMM dd, HH:mm EST"));
}, onPageError);
});
So we point at SampleService.ashx and the GetStockQuote method, passing a single parameter of the input symbol value. Then there are two handlers for success and failure callbacks.
The success handler is the interesting part - it receives the stock quote as a result and assigns its values to various 'holes' in the stock display elements.
The data that comes back over the wire is JSON and it looks like this:
{ "Symbol":"MSFT",
"Company":"Microsoft Corpora",
"OpenPrice":26.11,
"LastPrice":26.01,
"NetChange":0.02,
"LastQuoteTime":"2011-11-03T02:00:00Z",
"LastQuoteTimeString":"Nov. 11, 2011 4:20pm" }
which is an object representation of the data. JavaScript can evaluate this JSON string back into an object easily and that's the reslut that gets passed to the success function. The quote data is then applied to existing page content by manually selecting items and applying them. There are other ways to do this more elegantly like using templates, but here we're only interested in seeing how the data is returned. The data in the object is typed - LastPrice is a number and QuoteTime is a date.
Note about the date value: JavaScript doesn't have a date literal although the JSON embedded ISO string format used above ("2011-11-03T02:00:00Z") is becoming fairly standard for JSON serializers. However, JSON parsers don't deserialize dates by default and return them by string. This is why the StockQuote actually returns a string value of LastQuoteTimeString for the same date. ajaxMethodCallback always converts dates properly into 'real' dates and the example above uses the real date value along with a .formatDate() data extension (also in ww.jquery.js) to display the raw date properly.
Errors and Exceptions
So what happens if your code fails? For example if I pass an invalid stock symbol to the GetStockQuote() method you notice that the code does this:
if (quote == null) throw new ApplicationException("Invalid Symbol passed.");
CallbackHandler automatically pushes the exception message back to the client so it's easy to pick up the error message. Regardless of what kind of error occurs: Server side, client side, protocol errors - any error will fire the failure handler with an error object parameter. The error is returned to the client via a JSON response in the error callback. In the previous examples I called onPageError which is a generic routine in ww.jquery that displays a status message on the bottom of the screen. But of course you can also take over the error handling yourself:
$("#btnStockQuote").click(function () {
ajaxCallMethod("SampleService.ashx", "GetStockQuote",
[$("#txtSymbol").val()],
function (quote) {
$("#divStockDisplay").fadeIn(1000);
$("#stockCompany").text(quote.Company + " (" + quote.Symbol + ")");
$("#stockLastPrice").text(quote.LastPrice);
$("#stockQuoteTime").text(quote.LastQuoteTime.formatDate("MMM dd, hh:mmt"));
}, function (error, xhr) {
$("#divErrorDisplay").text(error.message).fadeIn(1000);
});
});
The error object has a isCallbackError, message and stackTrace properties, the latter of which is only populated when running in Debug mode, and this object is returned for all errors: Client side, transport and server side errors. Regardless of which type of error you get the same object passed (as well as the XHR instance optionally) which makes for a consistent error retrieval mechanism.
Specifying HttpVerbs
You can also specify HTTP Verbs that are allowed using the AllowedHttpVerbs option on the CallbackMethod attribute:
[CallbackMethod(AllowedHttpVerbs=HttpVerbs.GET | HttpVerbs.POST)]
public string HelloWorld(string name) { … }
If you're building REST style API's this might be useful to force certain request semantics onto the client calling. For the above if call with a non-allowed HttpVerb the request returns a 405 error response along with a JSON (or XML) error object result. The default behavior is to allow all verbs access (HttpVerbs.All).
Passing in object Parameters
Up to now the parameters I passed were very simple. But what if you need to send something more complex like an object or an array? Let's look at another example now that passes an object from the client to the server. Keeping with the Stock theme here lets add a method called BuyOrder that lets us buy some shares for a stock.
Consider the following service method that receives an StockBuyOrder object as a parameter:
[CallbackMethod]
public string BuyStock(StockBuyOrder buyOrder)
{
var server = new StockServer();
var quote = server.GetStockQuote(buyOrder.Symbol);
if (quote == null)
throw new ApplicationException("Invalid or missing stock symbol.");
return string.Format("You're buying {0} shares of {1} ({2}) stock at {3} for a total of {4} on {5}.",
buyOrder.Quantity,
quote.Company,
quote.Symbol,
quote.LastPrice.ToString("c"),
(quote.LastPrice * buyOrder.Quantity).ToString("c"),
buyOrder.BuyOn.ToString("MMM d"));
}
public class StockBuyOrder
{
public string Symbol { get; set; }
public int Quantity { get; set; }
public DateTime BuyOn { get; set; }
public StockBuyOrder()
{
BuyOn = DateTime.Now;
}
}
This is a contrived do-nothing example that simply echoes back what was passed in, but it demonstrates how you can pass complex data to a callback method.
On the client side we now have a very simple form that captures the three values on a form:
<fieldset>
<legend>Post a Stock Buy Order</legend>
Enter a symbol: <input type="text" name="txtBuySymbol" id="txtBuySymbol" value="GLD" />
Qty: <input type="text" name="txtBuyQty" id="txtBuyQty" value="10" style="width: 50px" />
Buy on: <input type="text" name="txtBuyOn" id="txtBuyOn" value="<%= DateTime.Now.ToString("d") %>" style="width: 70px;" />
<input type="button" id="btnBuyStock" value="Buy Stock" />
<div id="divStockBuyMessage" class="errordisplay" style="display:none"></div>
</fieldset>
The completed form and demo then looks something like this:
The client side code that picks up the input values and assigns them to object properties and sends the AJAX request looks like this:
$("#btnBuyStock").click(function () {
// create an object map that matches StockBuyOrder signature
var buyOrder =
{
Symbol: $("#txtBuySymbol").val(),
Quantity: $("#txtBuyQty").val() * 1, // number
Entered: new Date()
}
ajaxCallMethod("SampleService.ashx", "BuyStock",
[buyOrder],
function (result) {
$("#divStockBuyMessage").text(result).fadeIn(1000);
}, onPageError);
});
The code creates an object and attaches the properties that match the server side object passed to the BuyStock method. Each property that you want to update needs to be included and the type must match (ie. string, number, date in this case). Any missing properties will not be set but also not cause any errors.
Pass POST data instead of Objects
In the last example I collected a bunch of values from form variables and stuffed them into object variables in JavaScript code. While that works, often times this isn't really helping - I end up converting my types on the client and then doing another conversion on the server. If lots of input controls are on a page and you just want to pick up the values on the server via plain POST variables - that can be done too - and it makes sense especially if you're creating and filling the client side object only to push data to the server.
Let's add another method to the server that once again lets us buy a stock. But this time let's not accept a parameter but rather send POST data to the server. Here's the server method receiving POST data:
[CallbackMethod]
public string BuyStockPost()
{
StockBuyOrder buyOrder = new StockBuyOrder();
buyOrder.Symbol = Request.Form["txtBuySymbol"]; ;
int qty;
int.TryParse(Request.Form["txtBuyQuantity"], out qty);
buyOrder.Quantity = qty;
DateTime time;
DateTime.TryParse(Request.Form["txtBuyBuyOn"], out time);
buyOrder.BuyOn = time;
// Or easier way yet
//FormVariableBinder.Unbind(buyOrder,null,"txtBuy");
var server = new StockServer();
var quote = server.GetStockQuote(buyOrder.Symbol);
if (quote == null)
throw new ApplicationException("Invalid or missing stock symbol.");
return string.Format("You're buying {0} shares of {1} ({2}) stock at {3} for a total of {4} on {5}.",
buyOrder.Quantity,
quote.Company,
quote.Symbol,
quote.LastPrice.ToString("c"),
(quote.LastPrice * buyOrder.Quantity).ToString("c"),
buyOrder.BuyOn.ToString("MMM d"));
}
Clearly we've made this server method take more code than it did with the object parameter. We've basically moved the parameter assignment logic from the client to the server. As a result the client code to call this method is now a bit shorter since there's no client side shuffling of values from the controls to an object.
$("#btnBuyStockPost").click(function () {
ajaxCallMethod("SampleService.ashx", "BuyStockPost",
[], // Note: No parameters -
function (result) {
$("#divStockBuyMessage").text(result).fadeIn(1000);
}, onPageError,
// Force all page Form Variables to be posted
{ postbackMode: "Post" });
});
The client simply calls the BuyStockQuote method and pushes all the form variables from the page up to the server which parses them instead. The feature that makes this work is one of the options you can pass to the ajaxCallMethod() function:
{ postbackMode: "Post" });
which directs the function to include form variable POST data when making the service call. Other options include PostNoViewState (for WebForms to strip out WebForms crap vars), PostParametersOnly (default), None. If you pass parameters those are always posted to the server except when None is set.
The above code can be simplified a bit by using the FormVariableBinder helper, which can unbind form variables directly into an object:
FormVariableBinder.Unbind(buyOrder,null,"txtBuy");
which replaces the manual Request.Form[] reading code. It receives the object to unbind into, a string of properties to skip, and an optional prefix which is stripped off form variables to match property names. The component is similar to the MVC model binder but it's independent of MVC.
Returning non-JSON Data
CallbackHandler also supports returning non-JSON/XML data via special return types. You can return raw non-JSON encoded strings like this:
[CallbackMethod(ReturnAsRawString=true,ContentType="text/plain")]
public string HelloWorldNoJSON(string name)
{
return "Hello " + name + ". Time is: " + DateTime.Now.ToString();
}
Calling this method results in just a plain string - no JSON encoding with quotes around the result. This can be useful if your server handling code needs to return a string or HTML result that doesn't fit well for a page or other UI component. Any string output can be returned.
You can also return binary data. Stream, byte[] and Bitmap/Image results are automatically streamed back to the client. Notice that you should set the ContentType of the request either on the CallbackMethod attribute or using Response.ContentType. This ensures the Web Server knows how to display your binary response. Using a stream response makes it possible to return any of data.
Streamed data can be pretty handy to return bitmap data from a method. The following is a method that returns a stock history graph for a particular stock over a provided number of years:
[CallbackMethod(ContentType="image/png",RouteUrl="stocks/history/graph/{symbol}/{years}")]
public Stream GetStockHistoryGraph(string symbol, int years = 2,int width = 500, int height=350)
{
if (width == 0)
width = 500;
if (height == 0)
height = 350;
StockServer server = new StockServer();
return server.GetStockHistoryGraph(symbol,"Stock History for " + symbol,width,height,years);
}
I can now hook this up into the JavaScript code when I get a stock quote. At the end of the process I can assign the URL to the service that returns the image into the src property and so force the image to display. Here's the changed code:
$("#btnStockQuote").click(function () {
var symbol = $("#txtSymbol").val();
ajaxCallMethod("SampleService.ashx", "GetStockQuote",
[symbol],
function (quote) {
$("#divStockDisplay").fadeIn(1000);
$("#stockCompany").text(quote.Company + " (" + quote.Symbol + ")");
$("#stockLastPrice").text(quote.LastPrice);
$("#stockQuoteTime").text(quote.LastQuoteTime.formatDate("MMM dd, hh:mmt"));
// display a stock chart
$("#imgStockHistory").attr("src", "stocks/history/graph/" + symbol + "/2");
},onPageError);
});
The resulting output then looks like this:
The charting code uses the new ASP.NET 4.0 Chart components via code to display a bar chart of the 2 year stock data as part of the StockServer class which you can find in the sample download.
The ability to return arbitrary data from a service is useful as you can see - in this case the chart is clearly associated with the service and it's nice that the graph generation can happen off a handler rather than through a page. Images are common resources, but output can also be PDF reports, zip files for downloads etc. which is becoming increasingly more common to be returned from REST endpoints and other applications.
Why reinvent?
Obviously the examples I've shown here are pretty basic in terms of functionality. But I hope they demonstrate the core features of AJAX callbacks that you need to work through in most applications which is simple: return data, send back data and potentially retrieve data in various formats.
While there are other solutions when it comes down to making AJAX callbacks and servicing REST like requests, I like the flexibility my home grown solution provides. Simply put it's still the easiest solution that I've found that addresses my common use cases:
AJAX JSON RPC style callbacks
Url based access
XML and JSON Output from single method endpoint
XML and JSON POST support, querystring input, routing parameter mapping
UrlEncoded POST data support on callbacks
Ability to return stream/raw string data
Essentially ability to return ANYTHING from Service and pass anything
All these features are available in various solutions but not together in one place. I've been using this code base for over 4 years now in a number of projects both for myself and commercial work and it's served me extremely well. Besides the AJAX functionality CallbackHandler provides, it's also an easy way to create any kind of output endpoint I need to create. Need to create a few simple routines that spit back some data, but don't want to create a Page or View or full blown handler for it? Create a CallbackHandler and add a method or multiple methods and you have your generic endpoints. It's a quick and easy way to add small code pieces that are pretty efficient as they're running through a pretty small handler implementation. I can have this up and running in a couple of minutes literally without any setup and returning just about any kind of data.
Resources
Download the Sample
NuGet: Westwind Web and AJAX Utilities (Westwind.Web)
ajaxCallMethod() Documentation
Using the AjaxMethodCallback WebForms Control
West Wind Web Toolkit Home Page
West Wind Web Toolkit Source Code
© Rick Strahl, West Wind Technologies, 2005-2011Posted in ASP.NET jQuery AJAX
Tweet
(function() {
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
po.src = 'https://apis.google.com/js/plusone.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
