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.
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

Creating Custom Client Script in ASP.NET AJAX


Microsoft ASP.NET AJAX provides features that help you create client script and integrate it into ASP.NET applications. This includes a type system and extensions to existing ECMAScript (JavaScript) objects to give them the richness of .NET Framework classes. It also provides the ScriptManager control to manage these script libraries and any custom script in your application.

Creating Scripts

The Microsoft AJAX Library includes features that contribute to a richer, more powerful JavaScript development experience.

The Type class adds object-oriented features such as classes and inheritance to JavaScript programming. Any JavaScript object that is registered by using the Type class automatically has access to this functionality. For more information, see Extending JavaScript with ASP.NET AJAX.

The following example shows how to use the Type class to create and register a namespace and a class in a JavaScript file:



Demo.Person = function(firstName, lastName, emailAddress) {
    this._firstName = firstName;
    this._lastName = lastName;
    this._emailAddress = emailAddress;

Demo.Person.prototype = {

    getFirstName: function() {
        return this._firstName;

    getLastName: function() {
        return this._lastName;

    getName: function() {
        return this._firstName + ' ' + this._lastName;

    dispose: function() {
        alert('bye ' + this.getName());
Demo.Person.registerClass('Demo.Person', null, Sys.IDisposable);

// Notify ScriptManager that this is the end of the script.
if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

Extensions to JavaScript base types provide additional functionality for those types. For more information about these extensions, see the following topics:

The Sys.Debug class provides extensive debugging capabilities. For more information, see ASP.NET AJAX Debugging and Tracing Overview and the Sys.Debug class overview.

Component developers can create debug and retail versions of script files that are automatically managed by the ScriptManager control. You can identify debug versions of script files by including ".debug" as part of the script file name. For example, the following script file names identify retail and debug versions of a file:

  • Retail: MyScript.js

  • Debug: MyScript.debug.js

Integrating Client Script into ASP.NET Web Applications

Any ASP.NET Web page can access a script file by referring to it in a <script> block, as in the following example:

<script type="text/javascript" src="MyScript.js"></script>

However, a script invoked in this manner cannot participate in partial-page rendering or access certain components of the Microsoft AJAX Library. To make a script file available for partial-page rendering in an ASP.NET AJAX Web application, the script must be registered with the ScriptManager control on the page. To register a script file, create a ScriptReference object that points to the file question and that adds it to the Scripts collection. The following example shows how to do this in markup:

<asp:ScriptManager ID="SMgr" runat="server">
    <asp:ScriptReference path="MyScript.js" />

For script files to be processed correctly by the ScriptManager control, each file must include a call to the Sys.Application.notifyScriptLoaded method at the end of the file. This call notifies the application that the file has finished loading. The following example shows the code to use for this purpose:

if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

If your script is embedded in an assembly, you do not have to include a notification statement in the script. You also do not have to specify a path attribute in the script reference. However, you must provide the name of the assembly without the file name extension, as shown in the following example:

<asp:ScriptManager ID="SMgr" runat="server">
        Name="MyScript.js" Assembly="MyScriptAssembly"/>

This scenario is not common for page developers, because most controls with embedded script libraries reference their scripts internally. For more information, see Embedding a JavaScript File as a Resource in an Assembly.

You can also register scripts programmatically by creating script references in code and then adding them to the Scripts collection. For more information, see Dynamically Assigning ASP.NET AJAX Script References.

You can register scripts that are required for partial-page updates by using the registration methods of the ScriptManager control. You can use these methods in the following ways:

  • To generate client script in code, build a block of script as a string and pass it to the RegisterClientScriptBlock) method.

  • To add standalone script files that have no Microsoft AJAX Library dependencies, use the RegisterClientScriptInclude) method. 

  • To add script files that are embedded in an assembly, use the RegisterClientScriptResource method.


    Scripts that are registered by using these methods do not have localization support.

For a complete list of script-registration methods and their uses, see the ScriptManager control overview.

Any script blocks or inline script that you are registering must be inside the page's <form> element. Otherwise, the script is not registered with the ScriptManager control and cannot access ASP.NET AJAX functionality. For more information, see initialize Method.