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);
})();
