A few weeks ago, I had a project that was grounded in the .Net Framework v2.0 and Visual Studio 2005. The requirements were very focused on usability and speed so AJAX and jQuery were high on my list to use. Through the project, I learned that there isn't a large amount of information in one place that tells you how to setup a ASP.Net solution that uses jQuery and ASMX services to effectively transmit json data back and forth from the client. Because of this, I'll attempt to fill this void since there are still many developers and companies out there that have not been able to upgrade to Visual Studio 2008.
A Note About This Post:
This post is focused on Visual Studio 2005 with the ASP.Net 2.0 AJAX Extensions v1.0. The v3.5 of the extensions that came with ASP.Net v3.5 and Visual Studio 2008 have a few changes. While I will try to point out the differences, the core of this post is going to be focused on Visual Studio 2005 web application projects and v1.0 of the AJAX extensions. While we all love focusing on the latest and greatest, I'm aware that there are a large number of companies and professionals out there that are locked into using the older version of the software for a number of reasons.
Additions to VS2005 Used in This Post:
This post will be using the following additions to VS2005. Below are the items and links to their respective installers:
Code Downloads for This Post:
Creating and Configuring a New WAP:
Now that we have the required additions established, we're ready to create a new ASP.Net 2.0 Web Application Project. I'm not going to get into the details of how to do this; however, I want to stress that I'm NOT choosing an ASP.Net AJAX Enabled Web Application. I'm just choosing to create a new, basic ASP.Net Web Application Project. Now that the project has been created, we need to add a few references and add some information into the Web.Config file.
In the Solution Explorer, we'll need to add a reference to the AJAX Extensions v1.0 library, System.Web.Extensions.dll. By default, this library is located at C:\Program Files\Microsoft ASP.Net\ASP.Net 2.0 AJAX Extensions\v1.0.61025\ directory. After adding this reference, we can update our Web.Config file by including a reference to the ScriptHandlerFactory HttpHandler using the following snippet inside of the <System.Web> config section:
Setting Up an ASMX Web Service:
We have our new WAP setup and configured, it's time to write a simple ASMX web service and configure it so that it will be able to return JSON. To do this, let's add a web service to our project called JsonService.asmx and add the following code snippet to replace some of the defaults Visual Studio gives you:
Lines 1-3, I imported 3 additional namespaces to use in the code. System.Collections.Generics will be used in the next section. System.Web.Script.Services allow us to decorate the service and it's methods as Script methods for the ScriptHandlerFactory to use when making AJAX calls to and from the client.
Line 7 decorates the web service with the [ScriptService()] attribute.
Line 11 decorates the GetCustomer() web method with the [ScriptMethod()] attribute. This attribute tells the ScriptHandlerFactory that this method is allowed to be called from an Ajax Client. The properties inside of the attribute, ResponseFormat = ResponseFormat.Json, tells the ScriptHandlerFactory to send the response stream as a json string and not XML or Soap. If a response to the web service that is not formatted as json, the response will be returned as XML.
At this point, we can create the body of our web method in any fashion as long as it returns a string. If you are only passing base types, you can skip down to the Talking to the Server Using jQuery section; however, if you want to pass something a bit more complex, I recommend you continue to the next section.
This is just a simple string that, technically, we could have concatenated ourselves; however, you see how it converts the name-value pairs of the Dictionary object and turns them into a json Object with properties and string values.
Seems pretty simple. Now, let's turn our customer Dictionary into a CustomerInfo object with the same four properties. Below is the class definition:
Now, if we replace our Dictionary object with our CustomerInfo object we get code that looks similar to the following, easier to read, snippet:
Sadly, running the above code will give you the following error when you attempt to run it:
Now that we have our converter built, we can attach it to our serializer to get our json string as shown below:
Talking to the Server using jQuery:
In this client-side code, we're making a HTTP Post call to our web service by calling the web method of it directly. We are stating that we are sending and receiving data in json format. Despite the fact that our GetCustomer() web method does not take any parameters, we still need to send an empty json object in order to have json returned.
Lastly, we write an anonymous method to handle the successful message returned to us. The message is evaluated in order to be turned into a json object on the client side. We then validate the object by echoing the FirstName property in an alert box.
One thing to remind, this is for ASP.Net 2.0 Web Services. The response from ASP.Net 3.5 Web Services IS different in that the response message (msg) has it's content in a property only called "d". So instead of eval("(" + msg + ")"), it would be eval("(" + msg.d + ")").
This post has covered a large amount of steps to get a json-based web service infrastructure setup using jQuery and ASP.Net 2.0 web services. After a lot of low level research and asking questions to people, I realized that there was not a single location for this information. Hopefully, this post will help fill that gap.