ASP.NET "Atlas" Class Library Reference

Home

Back to "Atlas" Home

Walkthrough: Creating a Declarative Web Application with ASP.NET AJAX Futures CTP

Introduction

This walkthrough introduces the client-side, declarative syntax in Microsoft's ASP.NET AJAX Futures CTP. You will gain the most benefit from this walkthrough if you understand what ASP.NET AJAX is, what technical issues it is designed to solve, and what its essential components are.

This walkthrough illustrates how to use client script to call a remote Web service, using Xml Script client-side declarative markup instead of using client script to call the remote Web service. You will learn about the basic parts of an Xml Script declarative block, how to associate them with HTML elements on the page, and how they can invoke remote services.

Prerequisites

To complete the walkthrough, you need the following:

Microsoft Visual Studio 2005 and the .NET Framework version 2.0. For download information, visit the .NET Framework Developer Center Web site.
The ASP.NET AJAX v1.0 package installed on your computer. This MSI installer file includes a Visual Studio Content Installer (.vsi) for creating a blank ASP.NET AJAX Web application in Visual Studio.
The Futures January CTP package installed on your computer. This MSI installer file includes a Visual Studio Content Installer (.vsi) for creating a blank ASP.NET AJAX Web application with CTP extensions in Visual Studio.

Creating an ASP.NET AJAX CTP-Enabled Application

To begin, you will create an "ASP.NET AJAX CTP-Enabled Web application" in Visual Studio. When you use the Visual Studio project template to create a new, blank CTP Web application, Visual Studio creates a normal Web site folder structure with the following additional items:

An executable file named Microsoft.Web.Preview.dll, which resides in the Bin folder and provides server-side functionality.
A Web.config file with settings for ASP.NET AJAX Futures CTP applications.

To create a new ASP.NET AJAX CTP-Enabled Web application in Visual Studio

In the File menu, click New, and then click Web Site.
In the New Web Site dialog box, select the ASP.NET AJAX CTP-Enabled Web Application template item.
In the Location list, select File System.
Specify a path and language for the application, and then click OK.

Creating a Web Service with a Single Method

Next, you will create an ASP.NET Web service with a single method that can be called by your ASP.NET AJAX client script or markup. Web services that work with ASP.NET AJAX applications are not different from other ASP.NET Web services. ASP.NET AJAX applications can run in any browser and connect to any type of Web-based service; the server does not have to be running ASP.NET or Windows.

To create a new Web service

In Solution Explorer, right-click the name of the site, and then click Add New Item.
In the Add New Item dialog box, under Visual Studio installed templates, select Web Service.
Name the file HelloWorldService.asmx and clear the Place code in separate file check box.
Select the language you want to use.
Click Add.
Add the System.Web.Script.Services.ScriptService attribute to the service class. This attribute enables access to the Web service from ASP.NET AJAX client side code.

Add code to create a HelloWorld method in the Web service that returns the current date and time. The code must take a string as an input and return a formatted string with the current time and a message.

The following example shows a complete Web service that includes the HelloWorld method:

		
<%@ WebService Language="C#" Class="Samples.AspNet.HelloWorldService" %>
 
using System;
using System.Web;
using System.Web.Script.Services;
using System.Web.Services;
using System.Web.Services.Protocols;
 
namespace Samples.AspNet {
 
 [ScriptService]
 [WebService(Namespace = "http://tempuri.org/")]
 [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
 public class HelloWorldService  : System.Web.Services.WebService {
 
   [WebMethod]
   public string HelloWorld(String query)
   {
     string inputString = Server.HtmlEncode(query);
     if(!String.IsNullOrEmpty(inputString))
     {
       return String.Format("Hello, you queried for {0}. The "
         + "current time is {1}", inputString, DateTime.Now);
     }
     else
     {
       return "The query string was null or empty";
     }
   }
 }
}

Save and close the file.

Creating an ASP.NET Page

To create a Web page

Add a new ASP.NET page to your project and name it Declarative.aspx.
Note Be sure that you clear the Place code in separate file check box. For this walkthrough, you must create a single-file ASP.NET Web page.
Switch to Source view.
In the @ Page directive, set the Title attribute to Xml Script Declarative Walkthrough as shown in the following example:
```
		
<%@ Page Language="C#" Title="Xml Script Declarative Walkthrough" %>
```
C#

Copy the following markup and paste it into the file beneath the @ Page directive:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">  
<html xmlns="http://www.w3.org/1999/xhtml">
   
  <head id="Head1" runat="server">
   <style type="text/css">
     body { font: 11pt Trebuchet MS;
        font-color: #000000;
        padding-top: 72px;
          text-align: center }
   
     .text { font: 8pt Trebuchet MS }
   </style>
   
  </head>
  <body>
   <form id="Form1" runat="server">
     <asp:scriptmanager runat="server" id="scriptManager">
       <scripts>
         <asp:scriptreference path="PreviewScript" assembly="Microsoft.Web.Preview" />
       </scripts>
       <services>
         <asp:servicereference path="~/HelloWorldService.asmx" />
       </services>
     </asp:scriptmanager>
     <div>
       Search for
       <input id="SearchKey" type="text" />
       <input id="SearchButton" type="button"
           value="Search" />
     </div>
   </form>
   <hr style="width: 300px" />
   <div>
   <span id="results"></span>
   </div>
  </body>
</html>

Save the file, but do not close it yet.

Creating an Xml Script Declarative Block to Call the Web Service

In this part of the walkthrough, you will create a block of Xml Script declarative markup that enables you to call a Web service.

To create the elements for an Xml Script declarative block

In the Declarative.aspx page, following the <div> element you created in the previous procedure, add the following markup:
```
<script type="text/xml-script">
 <page xmlns="http://schemas.microsoft.com/xml-script/2005">
   <components>

     <textBox id="SearchKey" />

     <serviceMethodRequest id="helloService"
          url="HelloWorldService.asmx"
          methodName="HelloWorld">
       <bindings>
         <binding dataContext="SearchKey"
              dataPath="text"
              property="parameters"
              propertyKey="query" />
       </bindings>
       <completed>
         <invokeMethodAction target="resultsBinding"
           method="evaluateIn" />
       </completed>
     </serviceMethodRequest>

     <button id="SearchButton">
       <click>
         <invokeMethodAction target="helloService"
                method="invoke" />
       </click>
     </button>

     <label id="results">
       <bindings>
         <binding id="resultsBinding"
              dataContext="helloService"
              dataPath="result"
              property="text"
              automatic="false" />
       </bindings>
     </label>

   </components>
 </page>
</script>
   
```
Xml Script markup resembles ASP.NET markup in following the conventions of well-formed XHTML. However, the Xml Script markup differs in that it refers to objects and elements from the ASP.NET AJAX client script libraries.

The Xml Script declarative block uses a standard XHTML <script> element, except that the value of the type attribute is text/xml-script. The root element of an Xml Script block is the <page> element, which contains all other elements in a declarative block and has its own namespace, as identified in the value of the xmlns attribute.

The next element, <components>, refers to the section of an Xml Script declarative block that contains UI controls and components. The UI elements are declared as child elements of the <components> element. In this case, the page contains three UI elements: a <textBox> element, a <button> element, and a <label> element. These ASP.NET AJAX elements map to HTML elements in the page. For example, you associate the <textBox> element with the HTML text box control on the page by means of <textBox> element's id attribute.

The <button> element identifies which HTML control on the page invokes the remote method. The button's <click> element specifies the behavior for the click event of the HTML button. In this case, in the <invokeMethodAction> child element, a click invokes a remote method. The target attribute of the <invokeMethodAction> element references the <serviceMethodRequest> element where the remote method is specified.

The <serviceMethodRequest> element provides the URL to the Web service being called and the method being invoked (HelloWorld). The <bindings> child element specifies which client control's value will be passed as a parameter to the remote method, and the name of the parameter in the remote method. In its <completed> element, the <serviceMethodRequest> element specifies what to do when the remote method has completed. In this case, it invokes a local ASP.NET AJAX method specified in the method attribute, which will evaluate the return value from the server and assign it to a local object. The local object is the <label> element, which specifies in its targetElement attribute that it is associated with the <span> element whose ID value is results.

Make sure that the code following the @ Page directive looks like the following example, and then save and close the page.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml">
  
 <head id="Head1" runat="server">
   <style type="text/css">
     body { font: 11pt Trebuchet MS;
        font-color: #000000;
        padding-top: 72px;
          text-align: center }
  
     .text { font: 8pt Trebuchet MS }
   </style>
  
 </head>
 <body>
   <form id="Form1" runat="server">
     <asp:scriptmanager runat="server" id="scriptManager">
       <scripts>
         <asp:scriptreference path="PreviewScript" assembly="Microsoft.Web.Preview" />
       </scripts>
        <services>
          <asp:servicereference path="~/HelloWorldService.asmx" />
        </services>
     </asp:scriptmanager>
     <div>
       Search for
       <input id="SearchKey" type="text" />
       <input id="SearchButton" type="button"
            value="Search" />
     </div>
   </form>
   <hr style="width: 300px" />
   <div>
   <span id="results"></span>
   </div>
   <script type="text/xml-script">
    <page xmlns="http://schemas.microsoft.com/xml-script/2005">
     <components>

       <textBox id="SearchKey" />

       <serviceMethodReqest id="helloService"
            url="HelloWorldService.asmx"
            methodName="HelloWorld">
         <bindings>
           <binding dataContext="SearchKey"
                dataPath="text"
                property="parameters"
                propertyKey="query" />
         </bindings>
         <completed>
           <invokeMethodAction target="resultsBinding"
             method="evaluateIn" />
         </completed>
       </serviceMethod>

       <button id="SearchButton">
         <click>
           <invokeMethodAction target="helloService"
                  method="invoke" />
         </click>
       </button>

       <label id="results">
         <bindings>
           <binding id="resultsBinding"
                dataContext="helloService"
                dataPath="result"
                property="text"
                automatic="false" />
         </bindings>
       </label>

     </components>
    </page>
   </script>
 </body>
</html>

To test the ASP.NET AJAX application

Run the Declarative.aspx page.
Type some text into the search box, and then click the Search button.
The text is returned from the HelloWorld method in the Web service and displayed in the page.