Your SlideShare is downloading. ×
Changes between the ASP.NET
AJAX (“Atlas”) CTP and the
RTM Releases
Microsoft ASP.NET AJAX Team
January 2007
Applies to:
 ...
Summary
 The ASP.NET team is delivering a framework for generating Web applications that can take
 advantage of the latest...
Table of Contents
 Summary...................................................................................................
Properties, Methods, and Events...........................................................................27
  Browser Com...
Extender Controls..................................................................................................60
    ...
•     Performance -- We want to reduce load time and the size of the working set of scripts
      in the browser for both ...
debug and release                 The primary goal for this
                            deployments.                      ...
-   Support standards-based model.
                      -   Simplify browser-detection APIs.
 Client JavaScript    API ch...
Several APIs moved from these classes      calls.
                      to the new DomElement class.

                    ...
-   Reduce script size to improve load
                            times and performance.
 Client application     Provided...
has also been removed.                     Component developers
                                                          ...
changes only within its content
                         template.
                      Events have been added to the cli...
Summary of Changes from Beta to Beta 2
 A number of bug fixes and feature additions were made between the Beta and Beta 2
...
•   The Sys.Services.AuthenticationService.logout method now always redirects on
        successful completion. Previously...
Breaking Changes
The following are breaking changes:

•   The core assembly has been changed from Microsoft.Web.Extensions...
•   The client global registerNamespace function has been removed. You should change
    applications to use the existing ...
Developers using IExtenderControl and IScriptControl are required to add this
       call in their controls’ Render method...
Summary of Changes from RC to RTM
 This section summarizes bug fixes and feature additions that were made between the RC
 ...
release value from the configuration hierarchy. As was true in previous releases, the
       ScriptMode setting does not d...
Feature Matrix
 ASP.NET AJAX has been factored into two separate downloads in preparation for the RTM
 release. The follow...
Behavior class                                          

Binding component                                              ...
JavaScript Number type extensions                       

 JavaScript Object type extensions                       

 Ja...
the model used is a prototype. This change was made for several reasons; the following
table contrasts the two models.


 ...
Note In the beta version, there is some notion of support for closures. This is likely to
   be removed by RTM. In essence...
Array
Beta 2 change: Static Array APIs have been introduced as described here.

Beta2/RC change: The extensions on the Arr...
You continue to define namespaces and classes and interfaces using the Type.register*
APIs in the RTM release, but they ha...
When you consume interfaces, you can use reflection-like APIs to test for the types. When
you implement interfaces, you ad...
by attaching to the element’s event during initialization (for example). This required that the
event be disposed in the c...
required, rather than every time the object is created. The following example demonstrates
the RTM release model.

In Beta...
ev (this, Sys.EventArgs.Empty);
          }
     }
}

The design demonstrates the pattern of creating event handlers at th...
In the CTP release, there was little difference between the debug and release versions of
scripts, other than the release ...
}


Defining Type Descriptors
In the CTP release, you created objects that implement ICustomTypeDescriptorProvider
as a re...
Custom.UI.Button = function(associatedElement) {
    Sys.UI.Button.initializeBase(this, [associatedElement]);
}
Custom.UI....
Sys.UI.DomElement.getLocation($get('AddressLine1'));

Note the use of a new $get alias in this example, which is explained...
•   Use a new alias named $create for components that instantiates the component and
    sets properties, calls initialize...
model, you wrote handlers that would rely on the window.event global reference instead,
which was not browser independent....
Instance scripts (those generating the client components through the $create method)
continue to be queued with the Script...
Similarly, if a page developer references a script resource in an assembly using the
ScriptManager control, the NotifyScri...
Objects are required to be disposable to support the UpdatePanel scenarios, so you should
be sure that you implement the d...
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Changes between ASP.NET AJAX CTP and RTM
Upcoming SlideShare
Loading in...5
×

Changes between ASP.NET AJAX CTP and RTM

1,023

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
1,023
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
6
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Transcript of "Changes between ASP.NET AJAX CTP and RTM"

  1. 1. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases Microsoft ASP.NET AJAX Team January 2007 Applies to:  ASP.NET AJAX (formerly code-named "Atlas") o ASP.NET 2.0 AJAX Extensions o Microsoft AJAX Library Summary: Describes changes to the ASP.NET 2.0 AJAX Extensions and the Microsoft AJAX Library (both products formerly code-named "Atlas" and collectively referred to as ASP.NET AJAX) since the most recent Community Technical Preview (CTP) release. (73 printed pages) Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 1
  2. 2. Summary The ASP.NET team is delivering a framework for generating Web applications that can take advantage of the latest capabilities in client functionality that fall under the general banner of Asynchronous JavaScript and XML (AJAX) and Rich Interactive Applications (RIA). The new Microsoft ASP.NET AJAX addition to the .NET Framework includes a suite of JavaScript libraries (the Client Framework or Client FX) that are the foundation for creating rich behaviors and control-like functionality in the browser. ASP.NET AJAX also includes a set of a server controls and base classes for extender controls (the Server Framework or Server FX) that provides AJAX programming functionality and experiences for ASP.NET Web developers. ASP.NET AJAX functionality has been available to the public since October 2005 as a series of Community Technology Previews (CTPs), demonstrating everything from rich client behavior and asynchronous Web page postbacks to invoking and consuming Web services through JavaScript proxies. This paper describes the major differences between the final CTP release (made publicly available in July 2006) and the upcoming Microsoft ASP.NET AJAX v1.0 release (here called the RTM release). It also discusses a "futures" preview version (the Futures release) that adds functionality to the RTM release. (The RTM and the Futures releases together enable the full functionality and customer scenarios that were supported in the early CTP releases.) Further changes to the RTM and Futures releases may occur up to the Release Candidate (RC) version, which will be the final release before RTM. The document is organized in sections detailing specific functionality in the CTP release and how the same functionality is achieved with the RTM release. For each change there is a description of the reasons behind the change along with some technical insights. Document Conventions This document includes example code for features included in the previous CTPs as well as features to be packaged in the core and Futures components in the RTM release. The following colors are used in the code examples to provide clarity and allow quick differentiation: CTP release: Green RTM release: Red Futures release: Blue Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 2
  3. 3. Table of Contents Summary..................................................................................................................2 Document Conventions...............................................................................................2 Table of Contents.......................................................................................................3 Introduction..............................................................................................................5 Overview of Major Changes.........................................................................................7 Summary of Changes from Beta to Beta 2...................................................................13 Client FX..............................................................................................................13 Server FX.............................................................................................................14 Summary of Changes from Beta 2 to RC......................................................................14 Breaking Changes..................................................................................................15 Client FX..............................................................................................................16 Server FX.............................................................................................................16 Summary of Changes from RC to RTM.........................................................................18 Breaking Changes..................................................................................................18 In the client.......................................................................................................18 In the server......................................................................................................18 Server FX.............................................................................................................19 Client FX..............................................................................................................19 Feature Matrix..........................................................................................................20 Detailed Client FX Changes........................................................................................22 Prototypes and Closures.........................................................................................22 JavaScript Extensions (Client BCL)...........................................................................24 Array................................................................................................................25 Error.................................................................................................................25 Class and Type Definition, Reflection APIs.................................................................25 Abstract and Sealed Classes................................................................................25 Creating Types: Single and Multiple Inheritance.....................................................26 Interfaces .........................................................................................................26 Enums and Flags................................................................................................27 Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 3
  4. 4. Properties, Methods, and Events...........................................................................27 Browser Compatibility ...........................................................................................30 Building Debug and Release Scripts.........................................................................30 Doc Comments...................................................................................................31 Defining Type Descriptors....................................................................................32 Higher-level Component Framework........................................................................33 Component, Control, and Behavior Classes............................................................34 Creating and Finding Components and Elements....................................................34 Application Object and Life Cycle..........................................................................36 Property Change Notification................................................................................38 Disposing..........................................................................................................38 Bindings and Actions...........................................................................................39 Debugging............................................................................................................39 Globalization and Localization..................................................................................40 Globalization......................................................................................................40 Localization........................................................................................................42 Networking...........................................................................................................44 Calling Web Service Methods from Script...............................................................44 Application Services...............................................................................................47 Profile Service....................................................................................................47 Authentication Service........................................................................................49 Detailed Server FX Changes.......................................................................................50 Configuration........................................................................................................51 Configuration Section Entries...............................................................................51 System.Web Configuration Section Entries.............................................................52 System.Web.Extensions Section Entries................................................................53 Entries Required For IIS 7.0.................................................................................54 New Script Resource Handler, Compression, and Crunching........................................54 ScriptManager and ScriptManagerProxy Controls.......................................................56 Script References...............................................................................................56 Handling Debug and Release Scripts.....................................................................59 Script and Other Resource Registration APIs..........................................................59 Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 4
  5. 5. Extender Controls..................................................................................................60 Extender Controls and the Component Developer...................................................61 Script Controls......................................................................................................62 Script Descriptors..................................................................................................63 UpdatePanel Control..............................................................................................64 ScriptManager Control.........................................................................................64 Dynamic UpdatePanel Controls.............................................................................65 Client Events During Asynchronous Postbacks........................................................65 Developing Controls Compatible with the UpdatePanel Control.................................66 Sending Additional Data to the Client....................................................................67 Custom Error Handling and Redirection.................................................................68 Triggers............................................................................................................68 UpdateProgress control.......................................................................................69 Futures Differences................................................................................................69 Client-based and Server-based Types...................................................................71 Xml-script..........................................................................................................71 Defining Tag Prefixes..........................................................................................72 Creating Declarative Bindings...............................................................................72 References.........................................................................................................73 Introduction First, thank you for the great feedback and real-world usage data we have received during the pre-release stage of Microsoft ASP.NET AJAX! The differences between the Community Technology Preview (CTP) and the final RTM release of the Microsoft ASP.NET AJAX have been made with the following primary goals in mind: • Customer feedback -- We have made many changes based on community forums discussions and feedback from early adopters building Web applications using the CTP releases. • Developer productivity -- We want to provide extensive tool support in future releases of Visual Studio such as script authoring, script debugging, and client error handling and reporting. In addition, we want to improve the programming model with clear patterns and consistency with the .NET Framework design guidelines and principles where applicable. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 5
  6. 6. • Performance -- We want to reduce load time and the size of the working set of scripts in the browser for both release and debug scenarios. The amount of script and therefore the memory consumed by object instances were factors in our decisions. The table below summarizes the goals we have for different audience segments in providing a client-based JavaScript framework (Client FX) and an ASP.NET server-based framework (Server FX). Both frameworks are designed to be extensible in the future. For example, the Client FX is designed so that it meets our performance goals for today and can be used by server-based controls such as AutoCompleteExtender, which is located in the ASP.NET AJAX Control Toolkit, but it also includes hooks for adding xml-script support and bindings in a future release. Note Tool and design-time improvements described in this document are potentially targeted for the next release of Visual Studio code-named “Orcas.” Audience Goals Notes ASP.NET page - Incrementally update existing Developers utilize server controls developer Web applications with rich that hide JavaScript, but provide creating client functionality. the richness demanded by server-based today’s Web application - Use familiar, consistent pages developers. ASP.NET programming models and tools. - Reduce or eliminate the need to know or learn JavaScript. - Reduce or eliminate the need to write browser-specific code. - Leverage ASP.NET and .NET Framework programming skills. ASP.NET page - Define Client FX features to Page developers who want to developer simplify creation and use of create pure, client-based pages creating client- client components. independent of server technology based pages require a Client FX that enables - Provide a productive simplicity for tasks such as programming experience, such creating client objects and as possible IntelliSense support hooking events in a browser- in Visual Studio “Orcas”. independent manner. - Reduce or eliminate the need to write browser-specific script. ASP.NET - Provide a framework that The Client FX handles browser component enables the component detection and includes developer developer to create rich client extensibility. These specific functionality and behaviors for features, along with the broader ASP.NET server controls. Client FX and Server FX, provide component developers the - Demonstrate patterns and building blocks for creating concepts for creating script-rich controls. components that can support Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 6
  7. 7. debug and release The primary goal for this deployments. audience is to provide a foundation for a vibrant third- party component community. Overview of Major Changes The following tables provide a summary of the major differences between the CTP, RTM, and Futures releases. The feature areas are split into client and server groups, with information about sub-feature sets and the impact to the consuming audience. Feature Change Made & Purpose Effect Client FX Client type Changed from using closures to using Component developers system prototypes. and page developers can Purpose: now use a consistent model when creating - Improve overall performance and types on the Client FX. memory consumption of object instances. Page developers - Design for future possible consuming such types IntelliSense support in Visual Studio should see small code "Orcas". changes in addition to the - Provide better-defined design increased productivity of patterns. possible future IntelliSense and better debugging support in Visual Studio. Client events Changed the model for attaching to a Component developers DOM event and for exposing component and page developers can events. follow a simple, familiar pattern for defining and Purpose: attaching events. - Support a standard model and future extensibility. Page developers attaching events will find - Provide patterns similar to the .NET new APIs easier to follow. Framework. Client Compatibility is supported through Component developers compatibility layer browser detection and browser and page developers can capability and occurs completely on the leverage new APIs to client. help simplify multi- browser targeting. Purpose: Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 7
  8. 8. - Support standards-based model. - Simplify browser-detection APIs. Client JavaScript API changes. Page developers and extensions component developers Purpose: have new API signatures - Avoid conflicts and compatibility to avoid collisions with issues with other AJAX libraries and other APIs. frameworks. Client "classes" Changed the model for defining a class Component developers and other types to be prototype-based. Also changed obtain new models for the registration APIs to be sealed; in defining custom types. addition, abstract classes are no longer defined. Provided new enhancements to Page developers obtain error handling semantics. new aliases to instantiate Purpose: types, which eliminates previous complexity. - Faster object instantiation. - Improved overall performance and memory consumption of object instances. Debug and Defined an optional model for specifying Component developers release scripts debug and release versions of client can optionally provide scripts that can be independent of separate debug and server debug settings. release versions of their own scripts. Page developers always reference the release script in the ScriptManager Page developers have control and can specify debug mode network-optimized scripts separately for server and client code and scripts that support execution. Server administrators can debugging and possible specify the deployment mode future IntelliSense in configuration setting to ensure release Visual Studio “Orcas”. scripts are used in production. Purpose: - Possible tool support in Visual Studio “Orcas” for debug versions of scripts; scripts can also be leveraged by third parties. - Provide page developers access to highly optimized release scripts for production. Client Removed bindings and actions. These Component developers Component, types are defined in the Futures and page developers who Behavior, and release. The RTM release is designed in consume these types Control types a way for these to be layered in. need to modify their API Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 8
  9. 9. Several APIs moved from these classes calls. to the new DomElement class. Purpose: - Client FX simplification. - APIs can now be used without first needing to instantiate an object. - Reduction in script size improves load times and performance. Client networking Created a simplified and more flexible Page developers have design for calling Web service methods simplified and more from script. flexible ways to perform networking tasks. Added support for providing default callback functions and for passing a Developers must remove method name to the callback function. references to WCF (.svc) Web services, the iframe Replaced the instance page method in executor, and other the CTP release with static page features removed from method support. the Client FX. Removed support for calling WCF Web services (.svc files) from script. Removed the iframe executor class, which allowed cross-domain calls. Removed the following features from the CTP release: - Assembly-based method calls. - InitialData control. - Batching Web service calls. Purpose: - Simplify Web service calls from script. - Prepare for improved WCF implementation and integration planned for release with Visual Studio “Orcas.” - Eliminate potential security holes with cross-domain calls. - Remove features not being used from the Client FX to reduce size and improve performance. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 9
  10. 10. - Reduce script size to improve load times and performance. Client application Provided a simplified and more flexible Page developers can use services design for using the Membership and ASP.NET application Profile services from script; this is services more easily. aligned with the improvements in client networking for calling Web service methods from script. Added support for specifying default callback functions. Provided an additional Futures release implementation of Profile service as a component, aligned with the previous CTP release version. Purpose: Simplify ASP.NET application services access from script. Futures Release: Sys.* features have been moved to a Page developers who use Client high-level new namespace Sys.Preview.*. xml-script need to components, xml- change their code. Added support in the Client FX for a script, client data, model to define a simple type Changes may be required and type descriptor that can be consumed in the where properties are descriptors Futures release. moved from core objects in the RTM release to the The Futures release continues to Futures package. support xml-script and includes the following improvements: Component developers can write components - Bindings support unlimited nesting in components. using the RTM release that can also be used - Better namespace-to-component with Futures features. tag prefix assignments. Purpose: Refactor core Client FX for the RTM release. Feature Change Made & Purpose Effect Server FX ScriptManager Changed the ScriptManager control to Page developers obtain control support new UpdatePanel control fine-grained control over features, such as registration of scripts script handling. and style sheets. The error template Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 10
  11. 11. has also been removed. Component developers must register their Added new handling and features to component scripts and ScriptManager for referencing static resources with the scripts and Web resource-based scripts, ScriptManager control. and introduced a new event to enable custom script location resolution. Improved ScriptManager for debug and release script handling so it no longer infers debug status solely from the server configuration setting. Controls are now required to register their resources with the ScriptManager control. Purpose: Incorporate customer feedback and suggestions for giving page developers more control and flexibility in script handling and UpdatePanel usability. ExtenderControl The extender model was simplified to Component developers control enable support for one-control-to- obtain simplified models many-extenders scenarios. for creating extenders. Changed the model for defining and Page developers obtain registering a controls’ client “library” improved and simplified and "instance" script at run time to extender markup syntax. reduce the amount of page life-cycle knowledge required. The new model supports reduced JSON-style object creation or some future model. Added support for possible design-time improvements in Orcas for extenders to define their target control types. UpdatePanel Made changes to ensure that the Component developers control partial-page update model works in all must use registration known conditions. This means: models. - Controls must register their Page developers obtain resources (scripts, style sheets, new handling and logical etc.) through the ScriptManager models for the control. UpdatePanel control. - UpdatePanel no longer attempts to recognize changes in the entire document; instead, it monitors Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 11
  12. 12. changes only within its content template. Events have been added to the client PageRequestManager control to enable more scenarios related to asynchronous postbacks, such as animation effects and progress controls. UpdatePanel controls can now be added to a page both dynamically and declaratively. The trigger model has been improved by removing property triggers and adding postback triggers to allow full (synchronous) postbacks to be forced from within the UpdatePanel control. Purpose: Incorporate customer feedback and suggestions for giving component developers and page developers more flexibility and options for controlling partial-page updates and full postbacks. Tag prefix for Changed the tag prefix for ASP.NET Developers with pages server controls AJAX controls from <atlas:> to that include declarative <asp:>. controls must globally change the control tag Purpose: Normalize the namespace for prefix. declarative controls to be consistent with other ASP.NET controls. Futures release: Microsoft.Web.* features have been Changes may be required Server moved to a new namespace where properties are components Microsoft.Web.Preview.*. moved from core objects in the RTM release to the Purpose: Refactor core Server FX for Futures package. the RTM release. Component developers can write components using the RTM release that can also be used with Futures features. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 12
  13. 13. Summary of Changes from Beta to Beta 2 A number of bug fixes and feature additions were made between the Beta and Beta 2 releases of the ASP.NET AJAX 1.0 RTM. In this section we describe the differences in general terms. Later sections of this document describe the changes in more detail. Note: the following breaking changes have been made from Beta to Beta 2: • A new ScriptResource.axd handler has been added that requires an entry in the Web.config file. • Array.prototype extensions have been moved to static APIs on the Array object. • The ExtenderControl, IExtenderControl, and IScriptControl types must register themselves with the ScriptManager control in their PreRender method. • The Sys.UI.Key enumerations "return" and "delete" have been renamed to "enter" and "del". • The Sys.Services.AuthenticationService.logout method now always redirects on successful completion. Previously a redirect occurred only if you specified a URL. (If no URL is specified, the page redirects to itself.) • The Sys.Services.AuthenticationService.login and logout methods both call the completed callback function even if a redirect is about to occur. Previously, the callbacks were skipped. Client FX • Multiple DOM events can be created with the $addHandlers and $clearHandlers aliases. • Array.prototype extensions have been moved to static APIs on the Array object. • Sys.UI.Control APIs now include addCssClass, removeCssClass, and toggleCssClass. • The Sys.UI.Key enumerations return and delete have been renamed to enter and del • The new Date, Number, and String format and localeFormat methods use the Sys.CultureInfo.InvariantCulture and Sys.CultureInfo.CurrentCulture types. • Enum.parse supports a new case-insensitivity parameter. • The debug.trace and debug.dump APIs have been added. • Events have been added to the Sys.Application class for script loading exceptions. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 13
  14. 14. • The Sys.Services.AuthenticationService.logout method now always redirects on successful completion. Previously a redirect occurred only if you specified a URL. (If no URL is specified, the page redirects to itself.) • The Sys.Services.AuthenticationService.login and logout methods both call the completed callback function even if a redirect is about to occur. Previously, the callbacks were skipped. Server FX • A new ScriptResource.axd handler has been introduced that renders assembly- embedded script references and their resources, and also performs compression. The handler supports generation of client types for localization. Note This handler requires an entry in the Web.config file. If the entry is missing, you might see the following error: 'Sys' is undefined. • The ExtenderControl, IScriptControl, and IExtenderControl types must register with the ScriptManager control during their PreRender phase. The new model supports these types in more complex scenarios such as within templates in data- bound controls. • The ScriptManager control now includes the following: • New properties for globalization and localization support. • New APIs for supporting client focus with the UpdatePanel control's partial-page rendering. • A SupportsPartialRendering property that is based on browser capabilities. • A RegisterDispose method that can be used to track objects for disposal during partial rendering so that the object does not require a DOM element. • Globalization support through the generation of a client Sys.UI.CurrentCulture object that is determined from the server’s thread culture. By default, this value is determined based on the ACCEPT_LANG header in the browser request. • A ScriptLoadTimeout property for handling scripts in the client. Summary of Changes from Beta 2 to RC This section summarizes bug fixes and feature additions that were made between the Beta2 and RC releases of ASP.NET AJAX 1.0. Later sections of this document describe the changes in more detail. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 14
  15. 15. Breaking Changes The following are breaking changes: • The core assembly has been changed from Microsoft.Web.Extensions to System.Web.Extensions so that applications built with the RTM release will be compatible with the Orcas release. In your existing applications, you must do the following: • Ensure that your applications reference the new assembly, and remove references to Microsoft.Web.Extensions. • Ensure that your Web.config files now references the new assembly in all type references. • Ensure that Microsoft.Web.Extensions is uninstalled from the GAC. • The core namespaces have also been modified in keeping with changes to the core assembly. The Microsoft.Web.* namespaces have been changed to System.Web.*. In addition, individual types have been moved to other namespaces. In your existing applications, you must do the following: • Ensure that using or import statements all reference the new namespaces. Any fully qualified references must also be modified. • Change references to the server Timer control to System.Web.UI. • Change references to the ScriptModule class to System.Web.Handlers. • The Microsoft.Web.Extensions.Design namespace has been renamed to System.Web.Extensions.Design. The types in the namespace have also moved from Microsoft.Web.Design to System.Web.Design. In your application, you must update references and any using or import statements accordingly. • Developers who have created extender controls or script controls that implement the IExtenderControl and IScriptControl interfaces must add a call to ScriptManager.RegisterScriptDescriptors in the Render method of their controls. • The script compression module has been removed from the product. Script compression is handled directly in the script-resource handler. In your existing applications, you must remove the Web.config entry for the handler. • The <microsoft.web.extensions> section of the Web.config file has been renamed to <system.web.extensions>. • You must change existing Web.config files, both for the section itself and the section group. • The section contains a new sub-section named <scriptResourceHandler> that is used to control the caching and compression behavior of the handler. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 15
  16. 16. • The client global registerNamespace function has been removed. You should change applications to use the existing Type.registerNamespace function instead. • In the Futures release, scripts are referenced by using simpler names that no longer require the Microsoft.Web.Resources.ScriptLibrary prefix. You must modify all references. Client FX The following changes have been made to the client library: • Globalization support in the client library now includes parsing for Date and Number types. • The Debug.traceDump function does not perform recursion on DOM elements. • The Futures release includes converters for the DataRow, DataTable, and DataSet types. • Invoking Web service methods from JavaScript proxy methods now uses the same URL used to invoke .asmx services directly. This is an example of the old syntax: ...myService.asmx/js/myMethodName This is the new syntax: ...myService.asmx/myMethodName Server FX The following changes have been made for script resources: • ScriptReference types include a NotifyScriptLoaded property to instruct the framework to append the script notification script to resource-based script libraries. • The ScriptResource.axd handler has a new section in the Web.config file that enables developers and administrators to control caching and compression of script resources served through the handler. • The ScriptResource.axd handler supports the substitution logic in embedded Web resources as supported by the WebResource.axd handler. • The ScriptResource.axd handler supports scripts served from a request to pages directly under the default Web site. • The ScriptManager control supports UI-culture fallback logic for file-based static scripts defined using the ResourceUICultures property of a script reference. The following changes have been made for extender and script controls: • ExtenderControl base class and a new ScriptControl base class call on the new ScriptManager.RegisterScriptDescriptors API in their Render method. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 16
  17. 17. Developers using IExtenderControl and IScriptControl are required to add this call in their controls’ Render method. • The ScriptControlDescriptor, ScriptBehaviorDescriptor and ScriptComponentDescriptor ID property has been made consistent with its client representation. The ScriptControlDescritor and ScriptBehaviorDescriptor Name property has also been made consistent with its client-side representation. A ClientID property has been introduced in ScriptComponentDescriptor, ScriptControlDescriptor and ScriptBehaviorDescriptor. • An AddScriptProperty API is added to the ScriptComponentDescriptor allowing developers to set a property to some JavaScript expression directly. The following changes have been made for partial page updates: • The UpdateProgress control walks the naming container to locate the AssociatedUpdatePanel control. • Script components are automatically registered as disposable objects with the ScriptManager control. Client components therefore do not require an HTML element to be tracked for disposing. • The ScriptManager.SetFocus method works with HTML <input type="text" /> elements. • The MicrosoftWebAjaxWebForms.js library is referenced in pages only when there is at least one UpdatePanel control on the page and when the EnablePartialRendering property is set to true. • ScriptControl types are supported in UpdatePanel controls when the EventValidation property of the page is disabled. The following changes have been made for Web service proxies: • The WebServiceProxy class has been added to enable invocation of Web services that are not declared as ServiceReferences items in the ScriptManager control. This class is also used as an abstract JavaScript base class for generated JavaScript proxies for any Web services that are declared as ServiceReferences items. • Invoking Web service methods from JavaScript proxy methods now uses the same URL used to invoke .asmx services directly. This is an example of the old syntax: ...myService.asmx/js/myMethodName This is the new syntax: ...myService.asmx/myMethodName Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 17
  18. 18. Summary of Changes from RC to RTM This section summarizes bug fixes and feature additions that were made between the RC and RTM releases of ASP.NET AJAX version 1.0. Later sections of this document describe the changes in more detail. Breaking Changes The following are breaking changes. In the client • The Sys.UI.DomElement.setAccessibilityAttribute and Sys.UI.Control.set_role accessibility helper APIs have been removed. • The Sys.UI.ScriptLoader class is now a private object and renamed to Sys.UI._ScriptLoader. No APIs are considered public. • The script timeout handlers have been removed. This includes Sys.Application.add_loadTimedout, Sys.Application.remove_loadTimedout, Sys.Application.add_scriptLoadFailed, Sys.Application.remove_scriptLoadFailed, Sys.Application.get_scriptLoadTimeout, and Sys.Application.set_scriptLoadTimeout . • The Sys.Application.queueScriptReference method has been removed • The Debug class has been renamed to Sys.Debug. • The static Date.parse and Number.parse functions have been renamed to Date.parseInvariant and Number.parseInvariant. Similarly, Date.localeParse and Number.localeParse have been renamed to Date.parseLocale and Number.parseLocale. • The Number.parseInvariant method (formerly Number.parse) returns NaN if an invalid value is passed instead of throwing an exception. • The Date.parseInvariant method (formerly Date.parse) returns null if an invalid value is passed instead of throwing an exception. In the server • The ScriptManager.ScriptLoadTimeout property has been removed. • If the <deploymentmode retail=”false”> setting is on (the default), the ScriptManager control uses its ScriptMode property and the ScriptReference settings to determine whether to serve debug or release scripts. When the ScriptMode property is set to Auto or Inherit (the default), the ScriptManager control determines whether to send debug or release scripts based on the <compilation debug=”true|false”/> value in the application’s root-level Web.config file. The ScriptManager control no longer determines the debug or Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 18
  19. 19. release value from the configuration hierarchy. As was true in previous releases, the ScriptMode setting does not depend on the debug setting in an @ Page directive. • The System.Web.UI.Compatibility namespace and the validator controls that were compatible with asynchronous postbacks have been removed. • Accessing static page methods from script is disabled by default. You must explicitly set the EnablePageMethod property on the ScriptManager control to true for the PageMethods client proxy to be generated. • A System.Web.Script.Services.ScriptHandlerFactory handler type is now required to enable application services. You must register this handler in the Web.config file. • The configuration sections for System.Web.Extensions (other than the <jsonSerialization> section) are now marked to prevent their definition below the application root. Server FX The following changes have been made for registering script resources: • Some of the static registration methods of the ScriptManager class have additional overloads that take a Page object as a parameter. Scripts can therefore be registered independently of any UpdatePanel control that is being updated during the asynchronous postback. • Script compression is skipped if the browser is Microsoft Internet Explorer 6. • The ScriptManager control now supports a LoadScriptsBeforeUI property that allows page developers to have script references rendered at the bottom of the form rather than at the top (which is the default). • The Name property of the ScriptControlDescriptor and ScriptBehaviorDescriptor classes has been added to the list of properties that are sent to the $create method if the property is not empty. • The Function._validateParams function has been added to the release versions of scripts. Client FX The following changes have been made in the client FX: • The built-in types will return true when the isClass method is called on their type. • Many fixes in the Sys.UI.DomElement.getLocation method have been made to accommodate variations in implementations across browser types and versions and to accommodate the nesting of elements, borders, margins, and scrollbars. The fixes for the Futures release are listed in a subsequent section of this document. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 19
  20. 20. Feature Matrix ASP.NET AJAX has been factored into two separate downloads in preparation for the RTM release. The following lists the original CTP feature set and indicates where each feature now resides in the RTM release: the supported ASP.NET AJAX version 1.0 core release, or the community-supported Futures CTP release. Feature ASP.NET AJAX ASP.NET AJAX 1.0 CTP Server features Asynchronous client-to-server  networking Authentication as a Web service  AutoCompleteExtender class  ControlExtender class  Cross-browser Web Parts drag-and-drop  DragOverlayExtender control  PopupExtender class  Profile as a Web service  ScriptManager and ScriptManagerProxy  controls Static page methods as Web services  Timer control  UpdatePanel control  UpdateProgress control  Client Features Actions components  Authentication for JavaScript  AutoCompleteBehavior class  BatchResponse class  Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 20
  21. 21. Behavior class  Binding component  Button control  Calling .asmx Web services from  JavaScript Checkbox control  Click behavior  Component class  Control class  Counter class  Cross-browser Web Parts  Data control  Debug class  DragDropList control  DragDropManager component  DraggableListItem control  FadeAnimation component  Floating behavior  Hover behavior  Hyperlink control  Image control  Input control  JavaScript Array type extensions  JavaScript Boolean type extensions  JavaScript Error type extensions  Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 21
  22. 22. JavaScript Number type extensions  JavaScript Object type extensions  JavaScript String type extensions  JavaScript localization  JavaScript globalization  JSON serialization  Label control  Layout behavior  Opacity behavior  Popup behavior  Profile for JavaScript  Selector control  ServiceMethodRequest class  Sys.Data and Sys.UI.Data namespaces  Textbox control  Timer control Server Timer control  added Trace class  Validator controls  xml-script support  Detailed Client FX Changes Prototypes and Closures In the CTP release, "classes" or types were defined using a closure, effectively the constructor for the class. (Although these are not classes in the sense understood in the .NET Framework, we will refer to them as classes here for convenience.) In the RTM release, Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 22
  23. 23. the model used is a prototype. This change was made for several reasons; the following table contrasts the two models. Prototype Closure The constructor is required. The constructor contains the member declarations. The notion of "private" is handled by Members are truly encapsulated (private) convention. Members are defined with a to a class. name that includes the “_” prefix. Members are effectively shared, which Members are instance-based, which reduces the memory used by object increases the memory used by object instances. instances. Prototype provides a good load time in all In Internet Explorer, closure has slightly browsers; in Mozilla Firefox, prototype has better load time. significantly better load time. In all cases, script load time should be imperceptible to the end user. The main performance benefits of prototype are significantly less memory usage per object, and significantly faster object instantiation. Support for a tool’s IntelliSense and Tool support for IntelliSense and statement completion can obtain some type statement completion would require information based simply on reflection executing code by instantiating classes to without having to create the types. get the required type information. We are considering this for Visual Studio "Orcas," but not for Visual Studio 2005. While debugging, private members can be While debugging, private members cannot seen in the debugger. be easily seen by the debugger. Viewing member values in a tool (IDE) would require a number of steps. We investigated the performance advantage of prototypes over closures from many aspects —not just the memory consumed by object instances, but the instantiation of a typical application consisting of several classes with a variety of members. This performance investigation was conducted across multiple browsers, because the goal is a "best-fit" model across all browsers. If you write only ASP.NET pages and use ASP.NET AJAX framework client objects in custom script or through declarative xml-script, you should be unaffected by these changes. The CTP versions had support built-in for closures, to ensure that the base methods were capable of being called. This support is removed in the RTM release. You may be able to continue to have child ‘classes’ that inherit from prototype-based types, but you should not use closure-based types in any inheritance chain. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 23
  24. 24. Note In the beta version, there is some notion of support for closures. This is likely to be removed by RTM. In essence, however, closures can be used and sub-classed from prototype-style base classes. Developers should not create closures in cases where the closure may be used as a base type. The following example illustrates the salient points of the design in the RTM release; further description of the member patterns is provided later. registerNamespace("Custom"); // Prototype: Constructor Custom.Timer = function() { // Ctor creates private fields and calls base. Custom.Timer.initializeBase(this); this._interval = 1000; this._enabled = false; this._timer = null; } // Prototype: members Custom.Timer.prototype = { member1: function() { }, member2: function() { }, ... } Custom.Timer.registerClass('Custom.Timer', Sys.Component); In contrast, the CTP release uses a closure model, as shown in the following example. Type.registerNamespace("Custom"); // Closure: Constructor and members Custom.Timer = function() { Sys.Timer.initializeBase(this, [true]); var _interval = 1000; var _enabled; var _timer = null; this.member = function() ... } Custom.Timer.registerClass('Custom.Timer', Sys.Component); JavaScript Extensions (Client BCL) The CTP release contained a number of extensions to the existing built-in types in JavaScript, and these remain in the RTM release. However, they were redesigned to avoid potential conflicts with other AJAX frameworks where possible. (It is in extensions to the built-in types where collision can occur.) Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 24
  25. 25. Array Beta 2 change: Static Array APIs have been introduced as described here. Beta2/RC change: The extensions on the Array prototype have been replaced by static Array members that can be passed an Array object. Error In the CTP release, there was basic error handling, but this has been expanded. The Error prototype has been extended considerably in the RTM release to provide "typed" errors. In particular, component developers can throw errors (typically in debug scripts). In the RTM release, you can catch the exception and can inspect it to obtain further information about the error. The following example shows basic error handling to provide a richer exception message. function checkRange(index) { if (index > 10 || index < 0) { throw Error.argumentOutOfRange(“index”, index, "The index value must be between 0 and 10."); } } function myCallingFunction(value) { try { checkRange(value); } catch (e) { e.message = e.name + “:” + e.message + “nIndex value was: “ + e.actualValue; throw e; // bubbles up to the default error treatment } ... } When an exception is thrown, the error therefore contains information that will be handled by the browser. Class and Type Definition, Reflection APIs In the CTP release, you could create a number of variations of types, such as classes, interfaces, enums, and flags. This functionality has been changed in the RTM release. Abstract and Sealed Classes The CTP release allowed you to create abstract classes and sealed classes. In the RTM release, based on usage and a desire to improve performance, we removed the concept of a sealed or abstract class. This enables us to reduce the amount of script in the library and the complexity and performance impact required to implement these. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 25
  26. 26. You continue to define namespaces and classes and interfaces using the Type.register* APIs in the RTM release, but they have been moved from the Function.prototype property (where they were in the CTP release) to the Type.prototype property. This has no impact on you, though, because the CTP release aliased the window.Type property to Function. We have therefore changed the recommended usage of these APIs although either Function.* or Type.* can be used. Having all type APIs and reflection-based APIs defined using the Type.prototype property provides a consistent and logical design pattern. Creating Types: Single and Multiple Inheritance As in the CTP release, the RTM release creates types that can subclass from base types and can also implement any number of interfaces. In the CTP release, you could define a type that subclasses any number of base types. This has changed; in the RTM release you can use only single inheritance. Interfaces The definition of interfaces has been changed between the CTP release and the RTM release. The new definition reflects the removal of abstract functions and uses the prototype model. The following example shows a declaration of the interface in the CTP release. Custom.ICustomContract = function() { this.get_member = Function.abstractMethod; this.getAnotherMember = Function.abstractMethod; } Custom.ICustomContract.registerInterface("Custom.ICustomContract"); Custom.ICustomContract.prototype.get_member = function() { ...;} Custom.ICustomContract.prototype.getAnotherMember = function() { ... } The RTM release defines an interface similarly, but now uses the "typed" exceptions. It does not define abstract methods and does not define specific implementation. In release mode, interfaces do not have any code or member definitions. The following example shows an interface declaration in the RTM release. Custom.ICustomContract = function() { throw Error.notImplemented(); } Custom.ICustomContract.registerInterface("Custom.ICustomContract"); Custom.ICustomContract.prototype = { get_member: function() { throw Error.notImplemented();}, getAnotherMember: function() { throw Error.notImplemented(); } } Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 26
  27. 27. When you consume interfaces, you can use reflection-like APIs to test for the types. When you implement interfaces, you add their member definitions to the prototype for the type, rather than to the constructor as in the CTP release. Enums and Flags Beta 2 change: Sys.UI.Key["return"] is now Sys.UI.Key.enter, and Sys.UI.Key["delete"] is now Sys.UI.Key.del. The examples in this section show the differences between the CTP release and the RTM release for developers creating Enum and Flag structures. The following example shows an enum definition in the CTP release. Type.createEnum("MyEnum", "One", 1, "two", 2); The RTM release defines enums and flags as similar concepts, improves the usability of their definition, and allows doc comments as described later. MyEnum = function() { /// <summary>..</summary> } MyEnum.prototype = { One: 1, Two: 2 } MyEnum.registerEnum("MyEnum"); A number of enums are available in the client FX, such as Sys.UI.Key, Sys.UI.VisibilityMode, and Sys.UI.MouseButton. Properties, Methods, and Events In the CTP release, the model for defining properties was typically to define the getter and setter for the property, using methods with the prefixes "get_" and "set_". This model remains in the RTM release, but the member has moved to the prototype rather being defined in the closure, as described earlier. Similarly, methods are now defined using the prototype. There are two general kinds of events: ASP.NET AJAX (client object) events and events on DOM elements. For DOM element events, you can use simplified syntax to bind to DOM events in your classes. For client object events, you typically provide events that page developers can bind to, and that will be invoked through your class. Client FX objects can surface DOM events as their own events to provide a means for page developers to hook their own handlers. The following example shows this; the component exposes the element’s click event as a click event on the component directly. In the CTP release, an event on client ASP.NET AJAX objects was declared as a field in the constructor. Page developers hooking to the event had their handler called as a result of the event being invoked from the client object. Client objects hooked to a DOM element’s event Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 27
  28. 28. by attaching to the element’s event during initialization (for example). This required that the event be disposed in the component's dispose method, as shown in the following example. Custom.Button = function(...) { this.click = this.createEvent(); this.dispose = function() { if (_clickHandler) { this.element.detachEvent('onclick', _clickHandler); _clickHandler = null; } Custom.Button.callBaseMethod(this, 'dispose'); } this.initialize = function() { Custom.Button.callBaseMethod(this, 'initialize'); _clickHandler = Function.createDelegate(this, this._onClick); this.element.attachEvent('onclick', _clickHandler); } this._onClick = function() { this.click.invoke(this, Sys.EventArgs.Empty); ... } The preceding example also shows the model of calling attachEvent to attach the element’s click event. This is closer to the model for Internet Explorer, as demonstrated by the example for onclick. Script to provide your own handlers for object events might look like the following. // Simple global handler. var b = new Custom.Button(); b.click.add(OnClickHandler); function OnClickHandler() { ... } This design has been modified for various reasons. These include improving performance; providing a programming experience familiar from the .NET Framework; and following ECMAScript standards designs, as suggested in customer feedback. In the RTM release, you simply provide events that follow a naming pattern, in the way properties are exposed, using the "add_" and "remove_" naming convention. Tools can potentially interpret this pattern — for example, tools could use this pattern to determine events in IntelliSense. In high-level components, you now simply add a handler to an internal EventHandlerList object that is exposed through the get_events( ) member on the Component base class. Unlike the CTP release, the RTM release creates the event and event hookup at the time it is Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 28
  29. 29. required, rather than every time the object is created. The following example demonstrates the RTM release model. In Beta 2, a simplified syntax has been provided that automatically creates the delegate and that can be used to associate a number of DOM events and handlers at the same time. The following example shows how this is done. Custom.Button.prototype = { initialize: function() { Custom.Button.callBaseMethod(this, 'initialize'); // Create the handler and add the DOM handler this._handler = Function.createDelegate(this, this._onClickHandler); $addHandler(this.get_element(), 'click', this._handler); .. // Alternative syntax for single or multiple handlers. // When multiple handlers are involved, this // syntax greatly reduces the amount of code you need $addHandlers(this.get_element(), { click: this._onClickHandler, mouseover: this._onMouseOverHandler, mouseout: this._onMouseOutHandler, keydown: this._onKeyDownHandler, focus: this._onFocusHandler, blur: this._onBlurHandler }, this); } add_click: function(handler) { // Expose an event in this class this.get_events().addHandler('click', handler); }, remove_click: function(handler) { this.get_events().removeHandler('click', handler); }, dispose: function() { // Potential for dispose to be called more than once if (this._handler) { $removeHandler(this.get_element(), 'click', this._handler); delete this._handler; } .. // Alternative syntax that can remove multiple handlers // attached through $addHandlers $clearHandlers(this.get_element()); Custom.Button.callBaseMethod(this, 'dispose'); }, _onClickHandler: function() { // Invoke any page developer handlers that may be attached var ev = this.get_events().getHandler(this._handler); if (ev) { Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 29
  30. 30. ev (this, Sys.EventArgs.Empty); } } } The design demonstrates the pattern of creating event handlers at the required time. It uses the static methods of a new type named DomEvent to add and remove event hookups for the DOM element events themselves, using a standards-based model. Under the hood, these abstracted APIs provide browser compatibility support. Notice that in this example the aliases $addHandler, $removeHandler, $addHandlers, and $clearHandlers are shown. These are described later. In cases where you might be creating a number of DOM event hookups in client components and then removing them in the dispose method, you can use APIs or aliases that encompass more than one event hookup and that create the delegate for you. If you are wiring up your own handler, you now write code like the following. The event parameter is optional, but allows you to inspect the event, such as determining which button caused the click. var b = new Custom.Button(); b.add_click(OnClickHandler); function OnClickHandler(event) { .. } Browser Compatibility The CTP release used an abstraction model for browser compatibility that focused on APIs based on Internet Explorer. It used the server to provide a compatibility layer when the browser was not Internet Explorer, implemented by downloading an additional JavaScript file. In the RTM release version, this abstraction is retained, but it is based on standards and other improvements to the design. As a consequence, server intervention is no longer required. Instead, the client contains simple browser detection code based on capability, and abstraction APIs and other component-based APIs use such abstractions. For example, the event model described earlier uses the DomEvent.addHandler and DomEvent.removeHandler methods in a more standards-based way. Note the naming pattern of the event when using click instead of onclick. These API names are also consistent with the naming patterns used in components and types in the client. Building Debug and Release Scripts Our design scenarios call for us to provide a robust tools experience for ASP.NET AJAX. This requires supporting debug scripts and the ability to create release scripts for production environments. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 30
  31. 31. In the CTP release, there was little difference between the debug and release versions of scripts, other than the release versions were compressed to remove unneeded white space. In the RTM release there has been a considerable effort placed on providing a tools and programming experience that revolves around the use of debug versions of scripts. Debug versions of scripts now contain: • Support for doc comments. These are included to potentially augment IntelliSense in a tool, and to provide information to any developer using the APIs. • Error handling through the use of the Error extensions described earlier. • Named functions. Rather than anonymous functions, functions are pseudo-named, so that you get additional information, such as obtaining context within a stack trace. Doc Comments If you develop components, you can now provide type-description information in the debug scripts that define your custom types. This information will be useful for potentially augmenting the type information defined within Visual Studio “Orcas” for IntelliSense and for statement completion. (It will not be supported in Visual Studio 2005.) In addition, doc comments make it possible to use the Client FX validation model for compiler-type checking. Doc comments offer the following features: • You can define comments immediately in the constructor and in members. • You can define comments in the property getter, which infers the setter, and also in the event adder. • You can define comments in the interface constructor. • Comments support complex parameter or return types. An example of RTM release doc comments is shown in the following snippet of a border behavior. Type.registerNamespace('Custom.UI'); Custom.UI.BorderBehavior = function(element) { /// <summary>A border behavior</summary> /// <param name="element">Associated element</param> Custom.UI.BorderBehavior.initializeBase(this, [element]); } Custom.UI.BorderBehavior.prototype = { ... get_color: function() { /// <summary>Color</summary> /// <value type="String"/> return this._color; }, .. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 31
  32. 32. } Defining Type Descriptors In the CTP release, you created objects that implement ICustomTypeDescriptorProvider as a result of inheritance from the Component base class. You created a getDescriptor method and returned a TypeDescriptor object that was used to support xml-script declarative blocks and bindings. The following example shows the definition for Button control in the CTP release. (Note the use of the closure model.) Custom.Button = function(associatedElement) { Custom.Button.initializeBase(this, [associatedElement]); .. this.getDescriptor = function() { var td = Sys.UI.Button.callBaseMethod(this, 'getDescriptor'); td.addProperty('command', String); td.addProperty('argument', String); td.addEvent('click', true); return td; } In the RTM release, type descriptors have been removed for several reasons: • Xml-script requires considerable additional script and load processing logic, which affects script size and performance. This added unnecessary overhead in the more common cases where server controls produce rich client behavior. • Xml-script is oriented to the client, declarative programming model, which is currently included only in the Futures release. • Any behavior defined with declarative xml-script can be created by writing JavaScript code, without requiring the overhead of xml-script processing. (Of course, declarative xml-script might be easier with proper tools support.) • There is currently no tool support for the declarative xml-script, making it tedious and verbose to author. The features included in the Futures release continue to work with the RTM release, including xml-script. Therefore, you can write a component that can also be used by page developers who work with xml-script. To support this capability, the Futures release includes a TypeDescriptor object and is capable of generating such an object through a simple JSON field that is defined by the component itself. This is done without defining any true types in the RTM release. The following example shows the same Button example from earlier, but here as done in the RTM release. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 32
  33. 33. Custom.UI.Button = function(associatedElement) { Sys.UI.Button.initializeBase(this, [associatedElement]); } Custom.UI.Button.prototype = { .. } Custom.UI.Button.descriptor = { properties: [ {name: 'color', type: String } ], methods: [ .. ], events: [ {name:'click'}, .. ] } You can add the readOnly attribute, ensuring that the property has a default value, as shown in the following example. MyControl.descriptor = { properties: [{name: "title", type: String, readOnly: true}] } If you need to refer to a DOM element, use isDomElement:true, as in the following example. MyControl.descriptor = { properties: [{name: "...", isDomElement:true }] } Similarly, if the component defines some property that is a reference to another component (perhaps in a composition form), then the TypeDescriptor should reference the type. The following is an example. MyControl.descriptor = { properties: [{name: "...", type: Custom.Button }] } If you use xml-script in the Futures script, you can create a tag based on the type’s name. The Futures script will perform all the necessary steps to use the type descriptor. . Higher-level Component Framework The higher-level component feature set has been modified based on customer feedback, and for performance and working-set considerations. As shown in the earlier Button example, the DomEvent class uses a standards-based approach to provide a consistent abstraction API for DOM event hookup. This abstraction works across multiple browsers. Some APIs have been moved from their CTP release locations (often the Control class) to a new DomElement type in the RTM release, where they are defined as static functions. This reduces the size of the Control class and moreover allows you to use these helper methods, which typically wrap DOM element functionality, without instantiating a Control object. The following example shows how to use the DomElement object. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 33
  34. 34. Sys.UI.DomElement.getLocation($get('AddressLine1')); Note the use of a new $get alias in this example, which is explained later. Component, Control, and Behavior Classes The CTP release contained the Component, Control and Behavior classes, which defined many APIs and provided significant functionality. Both Control and Behavior are of type Component. This model continues in the RTM release. However, the semantics of these classes have been modified based on our study of their usage and on their original design implications. For example, in the CTP release, a Control instance was associated with a particular DOM element (see the constructor), and you could access that control through the DOM element. However, behaviors, although indirectly associated with a DOM element, required a Control instance and were maintained by Control using a collection property. The RTM release version makes working with DOM elements much more flexible. Both Control and Behavior are similar in concept and both are associated with a particular DOM element. However, they are now independent of each other. In the RTM release, you can associate a single Control instance with a DOM element, and access it through the control expando, as in the CTP release. If a behavior has a Name property, you can also reference the behavior by an expando based on its name. Multiple behaviors can be associated with the DOM element. The following example demonstrates $create, and uses a new $get alias defined in the RTM release to reference the controls and behaviors types. // Add a control and behavior to the GoShopping DOM element. $create(Custom.UI.Button, {}, {'click':'myHandler'}, {} $get('GoShopping')); $create(Custom.UI.BorderBehavior, {'name':'border'}, {}, {}, $get('GoShopping')); // Page developer accesses Button using the DOM element directly. var gs = $get('GoShopping'); gs.control.set_text('Sale items'); gs.border.set_color('red'); // Page developer obtains the behavior using the $ separator. var bb = $find(‘GoShopping$border); Creating and Finding Components and Elements In the CTP release, you were able to instantiate components in JavaScript, set properties, and call initialize. Alternatively, you could reference them using xml-script. The models for working with components in the RTM release: • Create components in JavaScript as before. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 34
  35. 35. • Use a new alias named $create for components that instantiates the component and sets properties, calls initialize, and so on. This is a powerful model that is also leveraged by server controls. • Use xml-script, which is still supported in the Futures release, and which performs the same logic as the $create alias in the RTM release. In the RTM release, when a component is instantiated with $create, a reference to the component is added to the global Application object. An alias is then available that allows page developers to locate components in cases where the page developer did not create the component—for example, the page developer can find a component that was created as a result of xml-script. $object, $find, and $create Aliases In the CTP release, you could use the $object('GoShopping') construct to reference a component created as a result of xml-script. The Futures release will continue to support this alias. In the RTM release code, we have introduced the $find method. You can use this method to locate all components created either by xml-script or by the $create alias in JavaScript. This means that you can get references to objects created by server controls and extenders, as well as by your own JavaScript and by xml-script declarations. Note In the beta version the $find syntax can be used to locate components, behaviors, and controls registered with the application using their ID. Controls obtain their ID from their DOM element’s ID. Behaviors obtain can obtain a unique ID which defaults to elementId$className — for example, AddressLine1$AutoCompleteBehavior — and are registered with Application. $create provides a powerful, concise syntax for creating a component in the client. When combined with Application methods, it even supports the scenario where circular references can be made between components in the client, as described in the "Application Object Life Cycle" section later in this document. $ and $get The CTP release defined a global alias named $( ) that mapped to the document.getElementById function. The $( ) alias is not supported in the RTM or Futures releases. Because we have a goal to not conflict with other AJAX frameworks, $( ) cannot be used; other frameworks define this function also. In its place, the RTM release defines a $get( ) function that performs the same task. $addHandler, $removeHandler The $addHandler and $removeHandler aliases in the RTM release provide a shorthand notation to create DOM event hookups and removal. Some examples were shown in the RTM Button control example earlier. In particular, however, the handler is passed a Sys.UI.DomEvent instance that provides a browser compatible event object. In the CTP Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 35
  36. 36. model, you wrote handlers that would rely on the window.event global reference instead, which was not browser independent. $addHandlers, $clearHandlers Beta 2 change: $addHandlers and $clearhandlers methods have been introduced. In many cases you want to hook up several handlers (delegates) to DOM events for the component. Rather than manually creating all the delegates and defining the handler for each, and then removing the handlers in the dispose event, you can use a condensed syntax to add and remove multiple handlers. The following provides an example. ... initialize: function() { ... var el = this.get_element(); $addHandlers(el, {[ 'mouseover': this._mouseHoverHandler, 'mouseout': this._mouseOutHandler, 'focus', this._focusHandler, 'blur', this_blurHandler ]}, this); Custom.UI.Hover.callBaseMethod(this, 'initialize'); }, dispose: function() { if (!disposed) $clearHandlers(); Custom.UI.Hover.callBaseMethod(this, 'dispose'); }, ... Application Object and Life Cycle Beta 2 change: Several new events have been introduced that handle errors when loading script libraries. The Sys.Application.initialize method might be called prior to window.onload (but after the DOM is ready). Page developers need to ensure that their page logic is performed in the pageLoad function. Beta 2 change: Script loading is performed through a client object that ensures scripts begin to be loaded (sequentially) and components begin to be created before the window.onload event. The components' initialize method is called as a result of the init event raised by Sys.Application. RC change: The default model for script loading has been modified. Library scripts are rendered declaratively at the top of the form, rather than being dynamically injected at the end of the form by calling Sys.Application.queueScriptReference. This means that the library scripts are available prior to the UI loading. The intention in the RTM release is to provide a flag on the ScriptManager control that enables page developers to select the script library loading process (before or after the UI) and manage their application scenario effectively. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 36
  37. 37. Instance scripts (those generating the client components through the $create method) continue to be queued with the ScriptLoader method at the end of the form. Page developers should continue to use the client pageLoad function for your client page logic. Component developers may want to attach to the load event of the Sys.Application object. RTM change: A property named called LoadScriptsBeforeUI has been added to the ScriptManager control with a default value of false. The flag enables developers to have the ScriptManager control render the script references either before the UI markup of the page or after it. Loading script after the UI might require changes to your application so that unexpected behavior does not occur before your application scripts are loaded and components are initialized. When scripts load after the UI, the page begins to appear quickly but the application may not yet be initialized. The page might not be in its final state, or users might interact with elements before script has finished downloading and executing. RTM breaking change: The Sys.ScriptLoader type has been made private and all members of this type are therefore also private. This change has been made given the change to the model for rendering script references, as described above. RTM breaking change: Because scripts are loaded through <script> tags, there is no requirement for the Sys.Application script-loading event handlers, so they have been removed. This includes the following events: • Sys.Application.add_loadTimedout • Sys.Application.remove_loadTimedout • Sys.Application.add_scriptLoadFailed • Sys.Application.remove_scriptLoadFailed • Sys.Application.get_scriptLoadTimeout • Sys.Application.set_scriptLoadTimeout The ScriptManager.ScriptLoadTimeout property of the ScriptManager class has been removed. Beta 2 change: "Dynamic" script library loading supports the Safari browser. File-based script libraries are required to have the following code at the end of their script file to notify the Sys.Application object that they have been loaded: if(typeof(Sys) !== “undefined”) Sys.Application.notifyScriptLoaded(); RC change: Script library references that result from an embedded Web resource (typically those from extender controls or script controls) by default have the preceding script automatically injected at the end of the script library. However, component developers can control whether this script is appended by setting the NotifyScriptLoaded property on a ScriptReference collection. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 37
  38. 38. Similarly, if a page developer references a script resource in an assembly using the ScriptManager control, the NotifyScriptLoaded property can be declaratively defined on the ScriptReference element. RTM change: Adding a call to the Sys.Application.notifyScriptLoaded method in script files is necessary only for asynchronous postbacks, but it is recommended that developers add a call to this method to script files that are served from disk. The CTP release had the concept of both a Runtime and an Application object. In the CTP release, the Application object was responsible for hooking to window events, and for locating the page developer’s pageLoad function (the load event handler) and pageUnload function (the unload event handler). The pageLoad function was guaranteed to be called after all the scripts had been loaded and after any objects defined in xml-script had been created and initialized. The RTM release brings Runtime and Application objects together into a single Application object. The RTM release continues to define the load and unload events, but also introduces an init event, which is typically used to create objects (using the $create alias). You can use the load event (mapped to pageLoad) to manipulate objects as before. In the RTM release, the load event is also raised during partial-page refreshes, and you can therefore run code in the pageLoad function to manipulate objects that may have been recreated as a result of the round trip. Objects that are created using the $create syntax are guaranteed to be instantiated; it also guarantees the beginUpdate method is called, properties are set, and the component's endUpdate and initialize method are called. In addition, objects can be registered with Application, thus allowing components to be managed and found through $find. The $create method defines the type to create, simple properties, event hookups, reference properties, and the optional DOM element. $create can handle scenarios in which components have references to other components. Ordinarily page developers do not need to need to call $create, because the server FX handles all $create logic from extender controls and script controls. Property Change Notification Both the CTP and the RTM releases define property-change events. In the RTM release, if you are developing components, you continue to raise the property-changed event for properties in your components that may require binding, or for external event listeners. The base component type is INotifyPropertyChange. Disposing In the CTP, the base Sys.Component type implemented the Sys.IDisposable interface, which defines the dispose method. This continues in the RTM release. However, a further interface has been introduced, named Sys.INotifyDisposing, which is defined in Sys.Component. This interface allows bindings in the Futures to listen to objects being disposed, and therefore be separate components in their own right. Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 38
  39. 39. Objects are required to be disposable to support the UpdatePanel scenarios, so you should be sure that you implement the dispose method in such a way that it handles being called more than once. In the Button example shown in the events section, the dispose method shows checking for the click handler and calling $removeHandler and delete only if defined. Calling the $clearHandlers function performs this logic automatically for handlers that were bound using the $addHandlers function. You should also ensure that any child components or objects being manually disposed are checked, because Application does not guarantee the order of objects being disposed automatically. Bindings and Actions The CTP release defined bindings on a component. Therefore a binding required a component so that the binding could be added to the component. The RTM release does not directly support bindings, but given the Sys.INotifyDisposing interface, bindings in the Futures scripts can (for example) be notified of objects being disposed and therefore be self-managing. Bindings in the Futures scripts can therefore be created without a component or demand on the RTM release; this also means that bindings can be declared more freely than in the CTP release. Bindings in the Futures release now obtain both a source and a target object reference and can listen to the disposing event of those objects. When an object is being disposed, the associated binding can now dispose of itself independently. Debugging RTM breaking change: The client Debug class has been renamed to Sys.Debug. This avoids any potential collision with other frameworks. The Sys.Debug class allows you to output debug information to the browser console, to the Visual Studio debugger output window, and in Internet Explorer, to a <textarea> element in the page. Sys.Debug supports methods to generate trace information, to throw an assert, and to display an object dump. The following snippet shows a simple example of using a <textarea> element to display debugger information. This is the code in the script file: onClick: function(e) { this.set_checked(!this._checked); Sys.Debug.trace("Element: " + this.get_element()); Sys.Debug.traceDump("Component: " + this); This is the code in the .aspx file: <script type="text/javascript"> function pageLoad() { $create(Custom.UI.CheckBox,{},{},{}, $get("checkbox")); Changes between the ASP.NET AJAX (“Atlas”) CTP and the RTM Releases 39

×