Documentation for: ASP.NET Ajax Version 1.0

This documentation is for a previous version. For the current released version, see the ASP.NET Ajax documentation on MSDN.

 

 

 

 

 

 

 

Skip Navigation Links.
Tutorials
Sample ASP.NET AJAX Application
ASP.NET AJAX and JavaScript
Extending JavaScript with ASP.NET AJAX
Creating Custom Client Script in ASP.NET AJAX
Dynamically Assigning ASP.NET AJAX Script References
Globalizing a Date by Using Client Script
Embedding a JavaScript File as a Resource in an Assembly
Embedding Localized Resources for a JavaScript File
Adding Localized Resources to a JavaScript File
Creating Custom Client Events
The UpdatePanel Control
Introduction to the UpdatePanel Control
Creating a Simple ASP.NET Page with Multiple UpdatePanel Controls
Using the UpdatePanel Control with Data-Bound Controls
Using the UpdatePanel Control with Master Pages
Using the UpdatePanel Control with User Controls
Using the UpdatePanel Control with a Web Service
Customizing Error Handling for UpdatePanel Controls
Animating UpdatePanel Controls
Canceling an Asynchronous Postback
Giving Precedence to a Specific Asynchronous Postback
Working with PageRequestManager Events
The UpdateProgress Control
Introduction to the UpdateProgress Control
Programming UpdateProgress Controls in Client Script
The Timer Control
Introduction to the Timer Control
Using the Timer Control with Multiple UpdatePanel Controls
ASP.NET Application Services
Using Forms Authentication
Using Profile Information
Web Services
Exposing Web Services to Client Script
Calling Web Services from Client Script
ASP.NET AJAX Extensibility
Creating Custom ASP.NET AJAX Non-Visual Client Components
Creating Custom ASP.NET AJAX Client Controls
Creating an Extender Control
Adding Client Capabilities to a Web Server Control
Creating a Client Component Class Using the Prototype Model
Defining Custom Component Properties and Raising PropertyChanged Events
Releasing Component Resources

Exposing Web Services to Client Script in ASP.NET AJAX

Introduction

Microsoft ASP.NET AJAX enables you to call ASP.NET Web services (.asmx files) from the browser by using client script. This enhances the user experience for the Web application. The page can call server-based methods without a postback and without refreshing the whole page, because only data is transferred between the browser and the Web server.

ASP.NET AJAX automatically creates JavaScript proxy classes for Web services. Proxy classes are derived from the Sys.Net.WebServiceProxy class.

You can call a Web service method by calling the corresponding method of the JavaScript proxy class. For details, see Calling Web Services from Client Script.

ASP.NET AJAX also provides built-in support for JavaScript calls to ASP.NET application services such as profiles and membership authentication. For details, see ASP.NET Application Services.

Making Web Services Accessible from Script

In order for a Web service to be accessed from script, it must be an .asmx Web service whose Web service class is qualified with the ScriptServiceAttribute attribute. Individual methods to be called from script must be qualified with the WebMethodAttribute attribute.

The following example shows these attributes in Web service code.

[ScriptService]
public class SimpleWebService : System.Web.Services.WebService
{
    [WebMethod]
    public string EchoInput(String input)
    {
        // Method code goes here.
    }
}

<ScriptService> _
Public Class SimpleWebService
        Inherits System.Web.Services.WebService
    <WebMethod> _
    Public Function EchoInput(ByVal input As String) As String
        ' Method code goes here.
    End Function
End Class

You must configure the Web application to support calling Web services from script. In the Web.config file for the application, you must register the ScriptHandlerFactory HTTP handler, which processes calls made from script to .asmx Web services. For Web service calls that are not issued from ASP.NET AJAX script, the handler delegates the call to the default handler. The following example shows the Web.config element for adding the handler.

<system.web>
  <httpHandlers>
    <remove verb="*" path="*.asmx"/>    <add verb="*" path="*.asmx"      type="System.Web.Script.Services.ScriptHandlerFactory"       validate="false"/>
  </httpHandlers>
<system.web>

When you install Microsoft ASP.NET AJAX, these configuration settings are part of the Web.config file template for any new Web sites that you create in Microsoft Visual Studio 2005.

Exposing Web Services to Client Script in an ASP.NET Web Page

To enable an .asmx Web service to be called from client script in an ASP.NET Web page, you first add a ScriptManager control to the page. You reference the Web service by adding an asp:ServiceReference child element to the ScriptManager control and setting its path attribute to point to the Web service. The ServiceReference object instructs ASP.NET 2.0 AJAX Extensions to generate a JavaScript proxy class for calling the specified Web service from client script.

The following example shows how to enable a Web service named SimpleWebService.asmx to be called from script in an ASP.NET Web page.

<asp:ScriptManager runat="server" ID="scriptManager">
  <Services>
    <asp:ServiceReference
       path="~/WebServices/SimpleWebService.asmx" />
  </Services>
</asp:ScriptManager>

The ServiceReference object can reference a Web service only in the same domain. The Web service path can be relative, application relative, domain relative, or absolute. For absolute paths, you must make sure that the path is in the same domain.

When a page that contains this ScriptManager control is rendered, it creates a JavaScript proxy class for the SimpleWebService.asmx Web service. The proxy class has methods that correspond to each Web method in the SimpleWebService.asmx service. The page also contains JavaScript proxy classes that correspond to server data types that are used as input parameters or return values for the Web service methods. This enables you to write client script that initializes these parameters, and to pass them to the method call.

The InlineScript property of the ServiceReference object specifies how the JavaScript proxy class is included in the page. If InlineScript is set to false (the default), the proxy script is obtained by making a separate request. This option is better when multiple pages reference the same service and when browser caching is enabled.

If InlineScript is set to true, the proxy class script is included as an inline script block in the page. This can improve performance by reducing the number of network requests. This is especially true if there are many service references in the page and other pages do not reference the same service. If InlineScript is set to true, you must use a relative path. If the path is domain-relative, it must refer to the same Web application.

The following example shows a simple Web service called from script that displays the user's input and returns the current server time.

Calling Static Methods in an ASP.NET Web Page

You can add static page methods to an ASP.NET page and qualify them as Web methods. You can then call these methods from script as if they were part of a Web service, but without creating a separate .asmx file. To create Web methods in a page, import the System.Web.Services namespace and add a WebMethodAttribute attribute to each static method that you want to expose.

To be able to call static page methods as Web methods, you must set the EnablePageMethods attribute of the ScriptManager control to true.

The following example shows how to call static page methods from the client script to write and read session-state values.

This example is currently not available.
This example is currently not available.

For more information about session state, see ASP.NET Session State.