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.

 

 

 

 

 

 

 

Asynchronous Communication Layer Overview

Introduction

The Microsoft ASP.NET AJAX asynchronous communication layer enables a browser to call Web service methods on the server by using ECMAScript (JavaScript). It exposes APIs that JavaScript functions can use in any browser to call Web service methods on the server. These APIs use the functionality for browser asynchronous behavior provided by the browser's XMLHTTP object. For more information about the XMLHTTP object, see About Native XMLHTTP on the MSDN Web site.

The asynchronous communication layer provides a clear separation between the business and data tiers on the server, and the presentation tier on the client. The browser has control of the presentation tier and provides a rich and responsive user interface, and the server performs the business and data tier tasks.

This topic contains the following information:

Asynchronous Communication Layer Features

The asynchronous communication layer offers the following features:

  • Enables JavaScript code to perform asynchronous calls to the server.

  • Can invoke methods in Web services that are implemented as .asmx files.

  • Can invoke ASP.NET static page methods as if they were Web service methods.

  • Can be configured to enable and disable the ability to call Web services from ASP.NET AJAX applications.

  • Supports a variety of serialization formats for passing data between the browser and the server, including JavaScript Object Notation (JSON), string data, and XML data.

  • Makes Web service interactions easier by generating JavaScript proxies for Web services that can be accessed from client script.

  • Provides extensibility for client executors that are used by the proxy objects. An executor is a component that functions as an interface between a client Web request and the network or other media. You can write your own executor that plugs into the asynchronous communication layer. For more information, see XMLHttpExecutor Class.

  • Can be used with Medium trust.

Back to top

Background

The asynchronous communication layer provides an abstraction of low-level components in the browser and on the server that enable you to perform client-server communication in JavaScript.

AJAX

Asynchronous JavaScript and XML (AJAX) enables you to create more interactive and more responsive Web applications than those that rely exclusively on complete page postbacks. With AJAX-style programming, the browser can exchange only the data it needs with the server, without having to update the complete page.

AJAX relies on the following combination of technologies:

  • Asynchronous communication between the browser and server by using the XMLHTTP object that is built into browsers.

  • A format for exchanging data between the browser and server. This format usually is XML, but it can also be JSON (as in ASP.NET AJAX) or another format.

  • Data presentation in the browser by using XHTML, HTML, and CSS.

  • Client scripting that uses the browser document object model (DOM) and JavaScript to create a responsive user interface (UI).

JSON

JavaScript Object Notation (JSON) is a lightweight format for representing objects and their state. The asynchronous communication layer uses JSON as a serialization format instead of the SOAP format more typically used with Web services. Using JSON simplifies client-server interaction, because it eliminates the need for extensive client script to construct requests that use SOAP and XML.

note

You do not have to understand the details of JSON format or serialization unless you have to extend or customize system capabilities. For example, you might have to know JSON format if you want to modify the way that ASP.NET 2.0 AJAX Extensions serializes specific custom types.

Calling Web Service Methods

ASP.NET 2.0 AJAX Extensions enables you to call ASP.NET Web services from the browser by using client script. 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. This following code example shows how to expose a Web service method in an ASP.NET Web page.

This example is currently not available.

Making HTTP Requests

The previous example of calling a Web service method from script does not require detailed knowledge of HTTP requests. For more advanced scenarios, the asynchronous communication layer enables a JavaScript to make a request over the network to any HTTP end point by using the Sys.Net.WebRequest class.

The following example shows how to use a WebRequest object to implement GET and POST Web requests that connect to the specified URLs (HTTP end points).

This example is currently not available.

To run the example you need the following:

  • A ConnectingEndPoints.aspx test page. This page contains a button to run the script that makes a GET request and then a POST request. The results are returned asynchronously by the default Sys.Net.XmlHttpExecutor instance and are displayed in the page.

  • The GetTarget.htm and the PostTarget.aspx pages. These are the target pages for the GET request and the POST request, respectively.

  • The supporting ConnectingEndPoints.js script. This script does the actual work of making the requests, and it provides the handler function which receives the results of the request.

Client-Server Communication

The following illustration shows how the asynchronous communication layer communicates between the client and the server.

ACSC Communication
Client-server communication

In physical terms, part of the asynchronous communication layer is on the client in the form of downloaded scripts. The other part is on the server in the form of handlers and Web services.

Client Architecture

The client asynchronous communication layer consists of several JavaScript components. The following illustration shows the client architecture of the asynchronous communication layer.

ACSC Client Architecture
Client architecture

The client architecture contains two main groups: the communication group and the support group.

Communication Group

The communication group contains client script that performs Web services communication between the client and the server. Note that Web request handling is intrinsically an asynchronous process. The communication group is based on the browser’s XMLHTTP object and on executor objects that dispatch browser requests to the Web service.

Web Service Proxy Classes

In Microsoft ASP.NET AJAX, the asynchronous communication layer generates client-script proxy classes automatically. You can then use the JavaScript proxy objects to make asynchronous requests to the server from client script. There are two possible approaches to making a Web service request:

  • Calling Web services by using the HTTP POST verb. A POST request has a body that contains the data that the browser sends to the server. It does not have a size limitation. Therefore, you can use a POST request when the size of the data exceeds the intrinsic size limitation for a GET request. The client serializes the request into JSON format and sends it as POST data to the server. The server deserializes the JSON data into .NET types and makes the actual Web service call. During the response, the server serializes the return values and passes them back to the client, which deserializes them into JavaScript objects for processing.

  • Calling Web services by using the HTTP GET verb. This resembles the functionality of a POST request, with the following differences:

    • The client uses a query string to send the parameters to the server.

    • A GET request can call only a Web service method that is configured by using the [ScriptMethod(UseHttpGet = true)] attribute.

    • Data size is limited to the URL length allowed by the browser.

      note

      GET requests are not recommended for method calls that modify data on the server or that expose critical information. In GET requests, the message is encoded by the browser into the URL and is therefore an easier target for tampering. For both GET and POST requests, you should follow security guidelines to protect sensitive data.

Page Method Proxy Classes

Page methods provide the scripting infrastructure for client script to call a static method in an ASP.NET page (an .aspx page, master page, or .ascx control) as if it were a Web service method.

Support Group

The support group is responsible for handling proxy classes and the serialization required for client-server communication.

Authentication Proxy Class

The authentication proxy class is generated by the server authentication service. It enables the user to log in or log out through JavaScript in the browser without making a round trip to the server.

Profile Proxy Class

The profile proxy class is generated by the server profile service. It makes the current user's profile information available to the client through JavaScript without making round trips to the server. It also enables saving modified profile information to the server by using script.

JSON Serialization

The client JSON serialization component serializes JavaScript objects into JSON format. Deserialization is available by using the JavaScript eval function.

Although JSON is the default serialization format, individual methods in Web services and in ASP.NET Web pages can return alternative formats such as XML. The serialization format of a method can be specified with attributes. For example, the [ScriptMethod(ResponseFormat.Xml)] attribute causes a Web service method to return data in a browser-specific XMLDocument type. For more information, see XML DOM Properties in the MSDN Library and the ScriptMethodAttribute class overview.

Server Architecture

The server asynchronous communication layer consists of several components. The following illustration shows the server architecture of the asynchronous communication layer.

ACSC Server Architecture
Server architecture

The server asynchronous communication layer includes two main groups: a communication group and a support group.

Communication Group

The server communication group is the high-level interface between the server and the client. It contains the server communication components that correspond to similar components on the client.

Web Services

In the Web Services component, the server performs all the required processing and returns an appropriate response to the client.

Page Methods

The page-methods component enables a method in an ASP.NET page (an .aspx page, master page, or .ascx control) to be called as if it were a Web service method.

Support Group

Components for the support group handle additional tasks such as serialization and application services that are required for client-server data exchange.

JSON Serialization

The server JSON serialization component enables customizable serialization and deserialization of common .NET types to and from JSON format.

XML Serialization

The asynchronous communication layer supports returning XML types from a Web service. If a Web method returns an XmlDocument object, as specified by the server attribute [ScriptMethod(ResponseFormat.Xml)], the callback function receives the return value as a browser-specific XmlDocument type. For more information, see XMLDocument Property in the MSDN Library.

Authentication Service

The authentication service generates an authentication proxy class and makes it available to client script. This enables the user to log in or log out through JavaScript in the client.

Profile Service

The profile service generates a profile proxy class, which can be used in client script to get and set profile properties for the user identity associated with the current request. The profile service works for for authenticated users and for anonymous users when the anonymous identification feature is enabled.

Back to top

Code Examples

Calling Web Services from Client Script

Exposing Web Services to Client Script

Using Forms Authentication

Using Profile Information

Back to top

Class Reference

Client Types

Name

Description

WebServiceProxy Class

Enables calling a method of a specified Web service asynchronously.

WebRequest Class

Models the information needed by the asynchronous client-server communication infrastructure to make an HTTP request. This class is used by other asynchronous client-server communication classes.

WebRequestExecutor Class -

Provides the functionality for interfacing with the network to perform Web requests.

WebRequestManager Class

Manages the flow of network requests from the WebRequest class to the XMLHttpExecutor class that is responsible for making the actual network requests.

WebServiceError Class

Handles errors for the Sys.Net namespace classes.

XMLHttpExecutor Class

Makes asynchronous network requests using the browser's XMLHTTP support.

JavaScriptSerializer Class

Provides serialization and deserialization functionality.

AuthenticationService Class

Provides the client proxy class for the authentication service.

ProfileGroup Class

Defines a profile group.

ProfileService Class

Provides the client proxy class for the profile service.

Server Types

Name

Description

ScriptingAuthenticationServiceSection

Represents the configuration section for authentication service settings.

ScriptingProfileServiceSection

Represents the configuration section for profile service settings.

JavaScriptConverter

Provides an abstract base class for a custom type converter.

JavaScriptSerializer

Provides serialization and deserialization functionality.

JavaScriptTypeResolver

Provides an abstract base class for implementing a custom type resolver.

ScriptIgnoreAttribute

Specifies that a public property or public field will be ignored by the JavaScriptSerializer when serializing or deserializing an instance of a class.

SimpleTypeResolver

Provides a type resolver for managed types.

GenerateScriptTypeAttribute

Specifies that the server type must be generated in the proxy object.

ResponseFormat

Specifies how the Web method return type is serialized.

ScriptMethodAttribute

Specifies which HTTP verb is used to invoke a method, and the format of the response.

ScriptServiceAttribute

Indicates to the asynchronous communication layer that a Web service can be invoked from script.

AuthenticationServiceManager

Configures the location of the authentication service.

ProfileServiceManager

Configures the location of the profile service.

Back to top

Additional Resources

About Native XMLHTTP article on the MSDN Web site

http://www.json.org Web site

Back to top