ASP.NET Ajax Toolkit - getting a key-value pair from the auto complete extender

Autocomplete Extender is a nice control, no doubt. And free. I didn't check earlier versions but current solution uses JSON web services and pretty fast.
Originally the Autocomplete Extender lacked very important functionality - ability to operate with key-value pairs. If you think about that, the Google search auto complete serves its purpose - the resulting string IS the value which is important for the postback, but it is scarcely the case for the 98% of non-search applications. We need control to mimic dropdown list - so gimme ya money let me keep the value for the entered text! Such a functionality was added some time ago but regretfully the feature was left undocumented.

You need to make few small changes to the original example: add JavaScript handling on the client and modify Web Service to return more sophisticated array. The Web Service method has to generate the list with the items in {"First":"<Name>,"Second":"<Value>"} format. E.g.

{"First":"Nissan Oakville","Second":"34AF44d2-1190-f489"} 

Method AutoCompleteExtender.CreateAutoCompleteItem(name,value) can help to create proper format.

Page looks like this:

<script type="text/javascript" language="javascript">
function GetCode(source, eventArgs )
{
document.getElementById("hCode").value = eventArgs.get_value();
}
</script>

Enter Manufacturer: <asp:TextBox ID="txtManufacturer" runat="server"/><input name="hCode" type="hidden"/>
<ajaxToolkit:AutoCompleteExtender ID="AutoCompleteExtender1" runat="server"
TargetControlID="txtManufacturer"
ServicePath="~/WebServices/AutoCompleteService.asmx"
ServiceMethod="GetCompletionList"
CompletionInterval="100"
CompletionSetCount="20"
MinimumPrefixLength="2"
OnClientItemSelected="GetCode"/>

And this is a full web service code:

[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[ToolboxItem(false)]
[System.Web.Script.Services.ScriptService]
public class AutoCompleteService : System.Web.Services.WebService
{

[WebMethod]
[System.Web.Script.Services.ScriptMethod]
public string[] GetCompletionList(string prefixText, int count)
{
   List<string> names = new List<string>();
   using (SqlConnection conn = DbGateway.GetConnection())
   {
       SqlCommand cmd = new SqlCommand("GetManufacturersByPrefix", conn);
       cmd.CommandType = CommandType.StoredProcedure;
       cmd.Parameters.Add(new SqlParameter("@prefix", prefixText));
       cmd.Parameters.Add(new SqlParameter("@count", count));
       conn.Open();
       using (SqlDataReader reader = cmd.ExecuteReader())
       {
           while (reader.Read())
           {
               string item = AjaxControlToolkit.AutoCompleteExtender.CreateAutoCompleteItem
                   (reader["ManufacturerName"].ToString(),
                   reader["ManufacturerId"].ToString());
               names.Add(item);
           }
           reader.Close();
       }
       conn.Close();
   }
   return names.ToArray();
 }
} 

As a result if postback is required, the hCode element will hold the value, matching the text from txtManufacturers box and can be extracted from Request.Form collection.

P.S. Microsoft has to apply some serious ass-kicking to their Documentation Generation (or whatever) Department. Poor MSDN documentation and samples are unbearable and this tradition seems to infect the Microsoft-flavored open source community.