Callback methods will normally return JSON data based on data types that are serialized. However you can also return raw binary (or string) data from your service by returning a few special result types from your Callback methods and then accessing them via plain GET requests.

Direct access GET URLs look like this:
http://localhost/Ajax/AutoCompleteHandler.ashx?Method=GetImage&imageFile=sailbig.jpg

You specify the method to call in the Callback handler along with any of the named parameters each specified as a querystring parameter or POST parameter. Using this approach you can call Callback methods that return binary data types in these formats.

Special Return Types Supported

  • Stream
    Any arbitrary data can be returned as stream as long as you can force it into stream format. This allows you to return almost any kind of format such as bitmaps, binary files, strings etc. as long as the format supports turning into a Stream type.

    [CallbackMethod(ContentType="image/png")] public Stream GetStockHistoryGraph(string symbol) { StockServer server = new StockServer(); byte[] img = server.GetStockHistoryGraph(new[] { symbol }, "History for " + symbol.ToUpper(), 450, 300, 2); MemoryStream ms = new MemoryStream(img); return ms; }

  • byte[]
    Like Streams you can also return raw byte data using the byte[] data type:

    [CallbackMethod(ContentType="image/png")] public byte[] GetStockHistoryGraph(string symbol) { StockServer server = new StockServer(); byte[] img = server.GetStockHistoryGraph(new[] { symbol }, "History for " + symbol.ToUpper(), 450, 300, 2); return img; }

  • Bitmap
    Bitmap results are very common and you can return the Bitmap type from your Callback method to have the image rendered as a binary bitmap.

    [CallbackMethod(ContentType="image/png")] public Bitmap GetImage(string imageFile) { Bitmap img = new Bitmap(HttpContext.Current.Server.MapPath("~/images/" + imageFile)); return img; }

    Note that you can set the content type in the attribute which is recommended. If not provided Callback Handler will use the Bitmap's internal ImageFormat (RawFormat) if set properly (typically when you load from file on disk).

  • Raw String Results
    You can also return raw string results by using the ReturnAsRawString CallbackMethod attribute parameter. When this parameter is specified a string result type is not converted into JSON and instead fed back as raw string data. This can be useful to feed back custom HTML or Error Page Output.

    [CallbackMethod(ReturnAsRawString=true,ContentType="text/plain; charset=UTF-8")] public string GetCities() { var searchFor = HttpContext.Current.Request.QueryString["q"]; busCustomer customer = new busCustomer(); var res = (from cust in customer.Context.nw_Customers where cust.City.Contains(searchFor) orderby cust.City select new { City = cust.City, cust.CustomerID }).Distinct(); StringBuilder sb = new StringBuilder(); foreach (var city in res) { sb.AppendLine(city.City + "|" + city.CustomerID); } return sb.ToString(); }

    Content type is optional. The default content type for raw string results if not specified is text/html (default Response.ContentType). You can also override the content type in code with HttpContext.Current.Response.ContentType.

    Additionally you can also specify a querystring or POST parameter of ResultFormat=string to force string output as raw output rather than JSON encoded output in which case the ReturnAsRawString parameter is not required on the CallbackMethod attribute.

Not an AJAX feature
This feature is not really an AJAX feature but provides you the ability to create Services that can serve more than just JSON data. It also makes it easier to create pure REST APIs the handle multiple types of output and can serve as a great 'impromptu' handler implementation that doesn't require a new HttpHandler for each individual request - instead you can group many Http requests into a single CallbackHandler to complete a full Service API.