The other day I got a question about
how to call an ASP.NET ASMX
Web Service or PageMethods with the POST data from a
Web Form (or any HTML form for that matter). The idea is that you should be able
to call an endpoint URL, send it regular urlencoded POST data and then use Request.Form[]
to retrieve the posted data as needed. My first reaction was that you can’t do it, because ASP.NET ASMX AJAX services (as well as Page Methods and WCF REST AJAX Services) require that the content POSTed
to the server is posted as JSON and sent with an application/json or application/x-javascript content type. IOW, you can’t directly call an ASP.NET AJAX service with regular urlencoded data. Note that there are other ways
to accomplish this. You can use ASP.NET MVC and a custom route, an HTTP Handler or separate ASPX page, or even a WCF REST service that’s configured
to use non-JSON inputs. However if you want
to use an ASP.NET AJAX service (or Page Methods) with a little bit of setup work it’s actually quite easy
to capture all the form variables on the client and ship them up
to the server. The basic steps needed
to make this happen are: Capture form variables into an array on the client with jQuery’s .serializeArray() function Use $.ajax() or my ServiceProxy class
to make an AJAX call
to the server
to send this array On the server create a custom type that matches the .serializeArray() name/value structure Create extension methods on NameValue[]
to easily extract form variables Create a [WebMethod] that accepts this name/value type as an array (NameValue[]) This seems like a lot of work but realize that steps 3 and 4 are a one time setup step that can be reused in your entire site or multiple applications. Let’s look at a short example that looks like this as a base form of fields
to ship
to the server: The HTML for this form looks something like this: <div id="divMessage" class="errordisplay" style="display: none">
</div>
<div>
<div class="label">Name:</div>
<div><asp:TextBox runat="server" ID="txtName" /></div>
</div>
<div>
<div class="label">Company:</div>
<div><asp:TextBox runat="server" ID="txtCompany"/></div>
</div>
<div>
<div class="label" ></div>
<div>
<asp:DropDownList runat="server" ID="lstAttending">
<asp:ListItem Text="Attending" Value="Attending"/>
<asp:ListItem Text="Not Attending" Value="NotAttending" />
<asp:ListItem Text="Maybe Attending" Value="MaybeAttending" />
<asp:ListItem Text="Not Sure Yet" Value="NotSureYet" />
</asp:DropDownList>
</div>
</div>
<div>
<div class="label">Special Needs:<br />
<small>(check all that apply)</small></div>
<div>
<asp:ListBox runat="server" ID="lstSpecialNeeds" SelectionMode="Multiple">
<asp:ListItem Text="Vegitarian" Value="Vegitarian" />
<asp:ListItem Text="Vegan" Value="Vegan" />
<asp:ListItem Text="Kosher" Value="Kosher" />
<asp:ListItem Text="Special Access" Value="SpecialAccess" />
<asp:ListItem Text="No Binder" Value="NoBinder" />
</asp:ListBox>
</div>
</div>
<div>
<div class="label"></div>
<div>
<asp:CheckBox ID="chkAdditionalGuests" Text="Additional Guests" runat="server" />
</div>
</div>
<hr />
<input type="button" id="btnSubmit" value="Send Registration" />
The form includes a few different kinds of form fields including a multi-selection listbox
to demonstrate retrieving multiple values.
Setting up the Server Side [WebMethod]
The [WebMethod] on the server we’re going
to call is going
to be very simple and just capture the content of these values and echo then back as a formatted HTML string. Obviously this is overly simplistic but it serves
to demonstrate the simple point of capturing the POST data on the server in an AJAX callback.
public class PageMethodsService : System.
Web.Services.WebService
{
[WebMethod]
public string SendRegistration(NameValue[] formVars)
{
StringBuilder sb = new StringBuilder();
sb.AppendFormat("Thank you {0}, <br/><br/>",
HttpUtility.HtmlEncode(formVars.Form("txtName")));
sb.AppendLine("You've entered the following: <hr/>");
foreach (NameValue nv in formVars)
{
// strip out ASP.NET form vars like _ViewState/_EventValidation
if (!nv.name.StartsWith("__"))
{
if (nv.name.StartsWith("txt") || nv.name.StartsWith("lst") || nv.name.StartsWith("chk"))
sb.Append(nv.name.Substring(3));
else
sb.Append(nv.name);
sb.AppendLine(": " + HttpUtility.HtmlEncode(nv.value) + "<br/>");
}
}
sb.AppendLine("<hr/>");
string[] needs = formVars.FormMultiple("lstSpecialNeeds");
if (needs == null)
sb.AppendLine("No Special Needs");
else
{
sb.AppendLine("Special Needs: <br/>");
foreach (string need in needs)
{
sb.AppendLine(" " + need + "<br/>");
}
}
return sb.ToString();
}
}
The key feature of this method is that it receives a custom type called NameValue[] which is an array of NameValue objects that map the structure that the jQuery .serializeArray() function generates. There are two custom types involved in this: The actual NameValue type and a NameValueExtensions class that defines a couple of extension methods for the NameValue[] array type
to allow for single (.Form()) and multiple (.FormMultiple()) value retrieval by name.
The NameValue class is as simple as this and simply maps the structure of the array elements of .serializeArray():
public class NameValue
{
public string name { get; set; }
public string value { get; set; }
}
The extension method class defines the .Form() and .FormMultiple() methods
to allow easy retrieval of form variables from the returned array:
/// <summary>
/// Simple NameValue class that maps name and value
/// properties that can be used with jQuery's
/// $.serializeArray() function and JSON requests
/// </summary>
public static class NameValueExtensionMethods
{
/// <summary>
/// Retrieves a single form variable from the list of
/// form variables stored
/// </summary>
/// <param name="formVars"></param>
/// <param name="name">formvar
to retrieve</param>
/// <returns>value or string.Empty if not found</returns>
public static string Form(this NameValue[] formVars, string name)
{
var matches = formVars.Where(nv => nv.name.ToLower() == name.ToLower()).FirstOrDefault();
if (matches != null)
return matches.value;
return string.Empty;
}
/// <summary>
/// Retrieves multiple selection form variables from the list of
/// form variables stored.
/// </summary>
/// <param name="formVars"></param>
/// <param name="name">The name of the form var
to retrieve</param>
/// <returns>values as string[] or null if no match is found</returns>
public static string[] FormMultiple(this NameValue[] formVars, string name)
{
var matches = formVars.Where(nv => nv.name.ToLower() == name.ToLower()).Select(nv => nv.value).ToArray();
if (matches.Length == 0)
return null;
return matches;
}
}
Using these extension methods it’s easy
to retrieve individual values from the array:
string name = formVars.Form("txtName");
or multiple values:
string[] needs = formVars.FormMultiple("lstSpecialNeeds");
if (needs != null)
{
// do something with matches
}
Using these functions in the SendRegistration method it’s easy
to retrieve a few form variables directly (txtName and the multiple selections of lstSpecialNeeds) or
to iterate over the whole list of values. Of course this is an overly simple example – in typical app you’d probably want
to validate the input data and save it
to the database and then return some sort of confirmation or possibly an updated data list back
to the client.
Since this is a full AJAX service callback realize that you don’t have
to return simple string values – you can return any of the supported result types (which are most serializable types) including complex hierarchical objects and arrays that make sense
to your client code.
POSTing Form Variables from the Client
to the AJAX Service
To call the AJAX service method on the client is straight forward and requires only use of little native jQuery plus JSON serialization functionality.
To start add jQuery and the json2.js library
to your page:
<script src="Scripts/jquery.min.js" type="text/javascript"></script>
<script src="Scripts/json2.js" type="text/javascript"></script>
json2.js can be found here (be sure
to remove the first line from the file):
http://www.json.org/json2.js
It’s required
to handle JSON serialization for those browsers that don’t support it natively.
With those script references in the document let’s hookup the button click handler and call the service:
$(document).ready(function () {
$("#btnSubmit").click(sendRegistration);
});
function sendRegistration() {
var arForm = $("#form1").serializeArray();
$.ajax({ url: "PageMethodsService.asmx/SendRegistration",
type: "POST",
contentType: "application/json",
data: JSON.stringify({ formVars: arForm }),
dataType: "json",
success: function (result) {
var jEl = $("#divMessage");
jEl.html(result.d).fadeIn(1000);
setTimeout(function () { jEl.fadeOut(1000) }, 5000);
},
error: function (xhr, status) {
alert("An error occurred: " + status);
}
});
}
The key feature in this code is the $("#form1").serializeArray(); call which serializes all the form fields of form1 into an array. Each form var is represented as an object with a name/value property. This array is then serialized into JSON with:
JSON.stringify({ formVars: arForm })
The format for the parameter list in AJAX service calls is an object with one property for each parameter of the method. In this case its a single parameter called formVars and we’re assigning the array of form variables
to it.
The URL
to call on the server is the name of the Service (or ASPX Page for Page Methods) plus the name of the method
to call.
On return the success callback receives the result from the AJAX callback which in this case is the formatted string which is simply assigned
to an element in the form and displayed. Remember the result type is whatever the method returns – it doesn’t have
to be a string. Note that ASP.NET AJAX and WCF REST return JSON data as a wrapped object so the result has a ‘d’ property that holds the actual response:
jEl.html(result.d).fadeIn(1000);
Slightly simpler: Using ServiceProxy.js
If you want things slightly cleaner you can use the ServiceProxy.js class I’ve mentioned here before. The ServiceProxy class handles a few things for calling ASP.NET and WCF services more cleanly:
Automatic JSON encoding
Automatic fix up of ‘d’ wrapper property
Automatic Date conversion on the client
Simplified error handling
Reusable and abstracted
To add the service proxy add:
<script src="Scripts/ServiceProxy.js" type="text/javascript"></script>
and then change the code
to this slightly simpler version:
<script type="text/javascript">
proxy = new ServiceProxy("PageMethodsService.asmx/");
$(document).ready(function () {
$("#btnSubmit").click(sendRegistration);
});
function sendRegistration() {
var arForm = $("#form1").serializeArray();
proxy.invoke("SendRegistration", { formVars: arForm },
function (result) {
var jEl = $("#divMessage");
jEl.html(result).fadeIn(1000);
setTimeout(function () { jEl.fadeOut(1000) }, 5000);
},
function (error) { alert(error.message); } );
}
The code is not very different but it makes the call as simple as specifying the method
to call, the parameters
to pass and the actions
to take on success and error. No more remembering which content type and data types
to use and manually serializing
to JSON. This code also removes the “d” property processing in the response and provides more consistent error handling in that the call always returns an error object regardless of a server error or a communication error unlike the native $.ajax() call.
Either approach works and both are pretty easy. The ServiceProxy really pays off if you use lots of service calls and especially if you need
to deal with date values returned from the server on the client.
Summary
Making
Web Service calls and getting POST data
to the server is not always the best option – ASP.NET and WCF AJAX services are meant
to work with data in objects. However, in some situations it’s simply easier
to POST all the captured form data
to the server instead of mapping all properties from the input fields
to some sort of message object first. For this approach the above POST mechanism is useful as it puts the parsing of the data on the server and leaves the client code lean and mean. It’s even easy
to build a custom model binder on the server that can map the array values
to properties on an object generically with some relatively simple Reflection code and without having
to manually map form vars
to properties and do string conversions.
Keep in mind though that other approaches also abound. ASP.NET MVC makes it pretty easy
to create custom routes
to data and the built in model binder makes it very easy
to deal with inbound form POST data in its original urlencoded format. The West Wind West Wind
Web Toolkit also includes functionality for AJAX callbacks using plain POST values. All that’s needed is a Method parameter
to query/form value
to specify the method
to be called on the server. After that the content type is completely optional and up
to the consumer. It’d be nice if the ASP.NET AJAX Service and WCF AJAX Services weren’t so tightly bound
to the content type so that you could more easily create open access service endpoints that can take advantage of urlencoded data that is everywhere in existing pages. It would make it much easier
to create basic REST endpoints without complicated service configuration. Ah one can dream!
In the meantime I hope this article has given you some ideas on
how you can transfer POST data from the client
to the server using JSON – it might be useful in other scenarios beyond ASP.NET AJAX services as well.
Additional Resources
ServiceProxy.js
A small JavaScript library that wraps $.ajax()
to call ASP.NET AJAX and WCF AJAX Services. Includes date parsing extensions
to the JSON object, a global dataFilter for processing dates on all jQuery JSON requests, provides cleanup for the .NET wrapped message format and handles errors in a consistent fashion.
Making jQuery Calls
to WCF/ASMX with a ServiceProxy Client
More information on calling ASMX and WCF AJAX services with jQuery and some more background on ServiceProxy.js. Note the implementation has slightly changed since the article was written.
ww.jquery.js
The West Wind West Wind
Web Toolkit also includes ServiceProxy.js in the West Wind jQuery extension library. This version is slightly different and includes embedded json encoding/decoding based on json2.js.© Rick Strahl, West Wind Technologies, 2005-2010Posted in jQuery ASP.NET AJAX
