Changes between the ASP.NET AJAX (“Atlas”) CTP and the RC and RTM Releases

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. For details, see "Handling Library Scripts and Their Resources" later in this document.
• 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.

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

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

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.

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 for the section group.
  • The section contains a new sub-section called <scriptResourceHandler>, which used to control caching and compression behavior of the handler.
• 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.

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

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. Developers using IExtenderControl and IScriptControl are required to add this call in their controls’ Render method.
• ScriptControlDescriptor, ScriptBehaviorDescriptor and ScriptComponentDescriptor Name and ID properties have been made consistent with their client-side representations.
• 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 EventValidation 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

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.

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, 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 convention. Members are defined with a name that includes the “_” prefix.	Members are truly encapsulated (private) to a class.
Members are effectively shared, which reduces the memory used by object instances.	Members are instance-based, which increases the memory used by object instances.
Prototype provides a good load time in all browsers; in Firefox, prototype has 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.	In Internet Explorer, closure has slightly better load time.
Support for a tool’s IntelliSense and statement completion can obtain some type information based simply on reflection without having to create the types.	Tool support for IntelliSense and statement completion would require executing code by instantiating classes to 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 seen in the debugger.	While debugging, private members cannot 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&#0151;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.

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);

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

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.

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.

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.

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.

You continue to define namespaces and classes and interfaces using the Type.register* APIs in the RTM, 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.

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.

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(); }
}

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.

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.

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 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 &#0151; 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 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) {
            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) {
    ..
}

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.

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.

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.

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;
    },
    ..
}

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.

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 Sys.UI.DomElement as the type, 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. .

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.

Sys.UI.DomElement.getLocation($get('AddressLine1'));

Note the use of a new $get alias in this example, which is explained later.

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);

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.
• 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&#0151;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 &#0151; for example, AddressLine1$AutoCompleteBehavior &#0151; 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 are defining it also. In its place, the RTM release defines a $get( ) function, which 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 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');
},
...

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

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. You should continue to use the client pageLoad function for your client page logic.

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.

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.

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 on partial page refresh scenarios, 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, and that the beginUpdate method is called, properties are set, and the component's endUpdate and initialize method are called. In addition, objects may 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.

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.

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.

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.

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.

Beta 2 change: Globalization and localization features have been added.

RC change: In the RC release, Date and Number parsing can also be performed using the globalization feature set using the new parse and localeParse methods.

Globalization in the client FX is supported through the Sys.CultureInfo type. This type defines two JSON objects, InvariantCulture and CurrentCulture.

In the CTP release, the CurrentCulture type was set through a server handler that was called from the client application. In the RTM release, this type is written in-line to the page. The change removes a callback to the server, but an inline type cannot be cached in the client. However, the objects are small.

The server framework is capable of creating the client Sys.CultureInfo.CurrentCulture by serializing the .NET CultureInfo object for the given thread’s CurrentCulture at the point of rendering in the ScriptManager control. This means that you can programmatically define the Culture using server techniques in ASP.NET 2.0, which by default use a mapping from the ACCEPT_LANG header of the incoming request.

In the client, your code, and any type that results from server extenders, can use the format and localeFormat APIs added to the Number, Date, and String types, and the parse and localeParse APIs added to the Date and Number types. The following sample demonstrates formatting a Date object with a predefined CultureInfo object and parsing input for a Date object.

var d = new Date();
$('DateLocale').innerHTML = d.toFormattedString("M");

// Rendered output assuming a CultureInfo obtained for Culture=”fr” 
// 31, octobre

In the RTM release, the new APIs allow specific formatting.

var d = new Date();
$get('DateLocale').innerHTML = d.localeFormat("M");

// Rendered output assuming a CultureInfo obtained for Culture=“fr”
// 31, octobre

// Parse. This assumes that the input value follows the 'd' format'
var s = $get('TextBoxDate').value.trim();
var d = Date.localeParse(s, "d");
$get('Date').innerHTML = d;

To use globalization support, you must explicitly set the ScriptManager.EnableScriptGlobalization property to true, as shown in the following example:

<asp:scriptmanager runat=”server” EnableScriptGlobalization=”true” />

RC change: A number of bug fixes have been made in the RC release. In particular, the ResourceUICultures support on path-based script references has been fixed.

Localization support has been added to the RTM release. The mainline scenarios that are supported are:

• Client components have UI elements, exception messages, and other items that are private to the component. In this case, the client component can be provided localized resources through two means: using an embedded resource (and therefore a satellite assembly), or as part of the library script reference itself.
• Client components have public properties that can be set and therefore localized by the page developer directly. There are two possible scenarios here also: the component is handled through a server extender control or script control, or the component is created directly in the client by the page developer.

Localized resources for a component are provided as a JSON object and referred to in the component through the object. For example, in the client FX, exception messages are thrown in debug scripts where the message is referred to using the type Sys.Res.<ExceptionMessageKey>.

Localized Resources from Server Assemblies

RC change: The ScriptResource.axd handler can be configured for caching and compression. The handler now also supports the resource substitution logic that is supported by the WebResource.axd handler. You can add substitution references in the embedded Web resources that are then handled by the ScriptResource.axd handler.

Note: The substitution code (<%=WebResource() %>) inserts a Webresource.axd URL, and the <%= ScriptResource() %> code inserts a ScriptResource.axd URL.

RC change: The custom client type and namespace for the embedded resource for localized resources are registered automatically.

A script library’s resources are served and generated by the server based on the incoming browser's ACCEPT_LANG header. The script resource handler added in the RTM release is responsible for generating a stream to the client that contains both the script library code and the automatically generated resource for the given UICulture value. If needed, you can use ASP.NET code to set of the UICulture value; using the ACCEPT_LANG is simply the default model.

Component developers can leverage the .NET localization model for satellite resources (packaging, servicing benefits), and rely on automatic generation to serve the relevant resource through any UICulture fallback model. This means the normal .NET localization workflow and toolset all contribute to this model.

By default, localization is not enabled in a Web page; to use localization, you must set the ScriptManager.EnableScriptLocalization property to true, as shown in the following example:

<asp:scriptmanager runat=”server” EnableScriptLocalization=”true” />

The following snippet demonstrates creating a custom extender control that has localized resources. These resources are referenced through a custom type in the client. Assume that the project is a class library named Custom.UI.ToggleButton.

// AssemblyInfo.cs
// Define the script resources attributes.
// The WebResource defines the script library for the client behavior
[assembly:webResource("Custom.UI.ToggleButton.ToggleButtonBehavior.js"
    , "text/javascript")]
// The ScriptResource attribute references the WebResource attribute and  
// points to the name of the embedded RESX(as a resource), and defines the 
// custom client type.
[assembly: ScriptResource("Custom.UI.ToggleButton.ToggleButtonBehavior.js",
    "Custom.UI.ToggleButton.ToggleButtonBehavior", "Custom.UI.Res")]

// ToggleButtonBehavior.js
// Marked as embedded resource in the class library.
  ..
  this.get_element().innerHTML = Custom.UI.Res.unhoverText;
  ..

// ToggleButtonBehavior.resx, ToggleButtonBehavior.fr.resx
// ToggleButtonBehavior.ja.resx, ..
// Marked as embedded resource. These are compiled by Visual Studio to 
// embedded .resource ‘files’ . 
// The neutral culture is embedded in the main assembly, and others are
// embedded in satellite assemblies under the culture folder structure

In the consuming page for this extender, you declare the extender and the ScriptManager control as shown earlier. When the page runs, the ScriptManager control generates a script reference to the library script using the ScriptResource.axd handler. The request instructs the handler to obtain the library script and also to obtain the relevant resource for the given UI-culture. This resource set is then serialized to the defined custom type as indicated in the ScriptResource attribute above.

The following snippet demonstrates the script library output that is sent to the client.

..
// Type generated by the framework automatically
Type.registerNamespace('Custom.UI');
Custom.UI.Res={
    ""unhoverText":"©±",
    ""hoverText":"¤µ©±"
};

Localized Resources from Static, File-based Scripts

A script library’s resources are rendered by the server using a model that involves the ScriptManager control, but there is no built-in, on-the-fly process for combining the library with the relevant resource for the current UICulture. Instead, the server interprets the UICulture as described above, but the script library and its resource are expected to already have been combined prior, potentially through a build process. The build process could involve the assembly-based library and its resources and satellite assemblies.

In order to select the correct script file to serve for the request, you instruct the ScriptManager control which ResourceUICultures values are supported by using an attribute on the script reference, as shown in the following example:

<asp:scriptmanager runat="server" EnableScriptLocalization="true"
  ScriptMode="Release">
  <scripts>
    <asp:scriptreference path="~/scripts/Custom.UI.js"
      ResourceUICultures="en-GB, fr-FR, fr-CA, ja-JP, de-DE" />
  </scripts>
</asp:scriptmanager>

// If the UICulture on the thread is ja-JP, the following 
// script reference is rendered.
// (Note that ScriptMode is set to "Release".)

<script src=”../scripts/Custom.UI.ja-JP.js />

The ScriptManager control infers the UICulture from the thread in the server, interprets the script reference (providing some means of fallback), and sends a script library that corresponds to a given UICulture.

The client proxy design for Web services has been modified to simplify method invocation, and to provide greater flexibility in associating method calls to callback functions.

In the CTP release method definition, client invocation and callback was defined as shown in the following examples. The first example shows the CTP release server code that defines a Web service method.

public class MyService: System.Web.Services.WebService
{
[WebMethod]
public string MyWebMethod(int param1, string param2) {
    ...
}

The next example shows the CTP release client code that calls the method.

// Invoke method, specifying a "succeeded" callback function.
MyNS.MyService.MyMethod(126, "my value", OnComplete,
    OnTimeout, OnError, onAborted, "MyUserContext");

// Callback function.
function OnComplete(result, response, userContext) {
   // Use result.
}

The next two examples show the corresponding RTM release method definition. The RTM release server method looks like the following example.

[ScriptService]
public class MyService: System.Web.Services.WebService
{
    [WebMethod]
    public string MyMethod(int param1, string param2) {
        ...
    }

The RTM release client code to call the method looks like the following example.

// Invoke method, specifying callback functions and user context.
MyNS.MyService.MyMethod(126, "my value", OnSuccess, OnFailure,
    "MyUserContext");

// Callback function
function OnSuccess(result, userContext, methodName) {
    // Use result.
}

In the RTM release, you can specify default callback functions and a user context, so that calling the Web service method does not require you to pass these as parameters. The following client script sets default callback functions and then calls the Web service method twice with different parameters.

var Fs = MyNS.MyService;
Fs.set_defaultSucceededCallback(OnSuccess);
Fs.set_defaultFailedCallback(OnFailure);
Fs.set_defaultUserContext("MyUserContext");
Fs.set_timeout(100);

// Invoke method without specifying callback functions or user context.
Fs.MyMethod(126, "value one");
Fs.MyMethod(456, "value two");

Server Attributes

In the CTP release, server attributes already defined in the .NET Framework were used for specifying behavior when Web service methods were called. In the RTM release, new server attributes are defined to specify particular behavior. This change was driven by security concerns and to avoid reusing existing attributes where the semantics are different.

Specific changes to Web method attributes are:

• A [ScriptService] attribute is required on the Web service class in order for its methods to be called from client script.
• The [ScriptIgnore] attribute excludes properties or fields from JSON serialization, so that they do not appear on script proxies for a server type. This corresponds to the [XmlIgnore] attribute in the CTP release.
• The [GenerateScriptType( )] attribute generates script proxies for server types, in addition to types used as input parameters or return types on Web methods. This attribute can be added to the Web service class or to any Web service method. It corresponds to the [XmlInclude( )] attribute in the CTP release.

WebServiceProxy Class

The WebServiceProxy class was added to allow invocation of Web services that are not declared as service references with the ScriptManager control (using the <asp:ServiceReferences> element). WebServiceProxy is also used as an abstract JavaScript base class for generated JavaScript proxies for any Web services that are declared in the ServiceReferences collection.

Support for WCF Web Services

You can no longer call Windows Communication Foundation (WCF) Web services (.svc files) from script in the RTM release. This capability is superseded by an improved implementation which we plan to make available with full WCF integration in upcoming "Orcas" CTP releases.

Advanced Networking Scenarios Not Available in the RTM Release

The following networking features of the CTP release will not be available in the RTM release:

• The iframe executor. This feature provided support for cross-domain calls, and is not available in RTM release in part because of security concerns.
• The following infrequently used features:
  • Assembly-based method calls.
  • 80InitialData control.
  • Batching of Web service calls.

In the RTM release, we provide a simplified and more flexible design for using the Authentication and Profile services from script. The design is aligned with the design for calling user-defined .asmx Web services from script (see “Calling Web Service Methods from Script” earlier).

The RTM release version of the Profile service, in keeping with the Web service script proxy model, is not implemented as a component. However, an implementation of the Profile service as a component is provided in the Futures release.

The primary changes in the Profile service between the CTP and the RTM releases are:

• The class name has changed from Sys._Profile to Sys.Services._ProfileService.
• The global instance has moved from Sys.Profile to Sys.Services.ProfileService.
• We enable you to specify default callback functions for save, load, and errors.
• We added save and load methods that take a string array of parameters.
• We added support for profile groups.
• We enabled support for preloaded profile properties using ScriptManager and ProfileServiceManager control markup.
• We removed the AutoSave feature.
• We removed the saved, loaded, and propertyChanged events.

The version of the Profile service provided in the Futures release fills the gap between the CTP release Profile component and the RTM release Profile proxy, and has the following features:

• The class name is Sys.Preview.Services.Components.Profile.
• The xml-script markup is the same (<profile ...>).
• The component automatically loads the profile on page load if no alternative preloading is specified.
• The component includes the AutoSave feature.
• The component includes saved and loaded events.
• The component includes getProperty( ) and setProperty( ) methods.
• The component can be the target or source for a Binding component.

The following samples illustrate the use of the Profile service in the Futures release.

The first example illustrates preloading profile properties.

<!-- Preload specific properties with the page -->
<asp:ScriptManager>
  <ProfileService
     Path = "~/myapp/profileserviceurl.asmx"
     LoadProperties = "SimpleProperty, Group.GroupedProperty" />
</ asp:ScriptManager>

The following example illustrates loading profile properties.

// Load specific properties, after setting default completed
// and failed callback functions. Sys.Services.ProfileService.load(["SimpleProperty",
    "Group.GroupedProperty"]);

// Load all properties marked as "read access" in the Web service,
// after setting default completed and failed callback functions.
Sys.Services.ProfileService.load();

// Specify explicit callbacks rather than using defaults. "88" is 
// passed to the callback function as user context.
Sys.Services.ProfileService.load(props, loadCompletedCallback,
    failedCallback, 88);

The following example illustrates accessing properties.

var x = Sys.Services.ProfileService.properties.SimpleProperty;

var x = Sys.Services.ProfileService.properties.Group.GroupedProperty1;

var x = Sys.Services.ProfileService.properties.Group.GroupedComplexTypeProperty.AddressLine1;

The following example illustrates changing property values.

Sys.Services.ProfileService.properties.SimpleProperty = "value";

if(!Sys.Services.ProfileService.properties.Group) {
      Sys.Services.ProfileService.properties.Group =
          new Sys.Services.ProfileGroup();
}
Sys.Services.ProfileService.properties.Group.GroupedProperty1 =
    "group value";
Sys.Services.ProfileService.properties.Group.GroupedComplexTypeProperty =
    { AddressLine1: "abc", AddressLine2: "xyz" };

The following example illustrates saving property values.

// Save specific properties, after setting default success and
// fail callback functions.
Sys.Services.ProfileService.save(["SimpleProperty",
    "Group.GroupedProperty"]); 
// Save all properties in the .properties object, after 
// setting default completed and failed callback functions.
Sys.Services.ProfileService.save();

// Specify explicit callbacks, rather than using defaults. "88" is 
// passed to the callback function as user context.
Sys.Services.ProfileService.save(props, saveCompletedCallback,
    failedCallback, 88);

The following example illustrates the completed callback function signatures.

function loadCompletedCallback(numPropertiesLoaded, userContext, methodName) {...}

function saveCompletedCallback(numPropertiesSaved, userContext, methodName) {...}

The following examples illustrate the failed callback function signature.

function failedCallback(errorObject, userContext, methodName) {...}

The changes for the Authentication service between the CTP and the RTM releases are:

• You can set default callback functions for login, logout, and errors.
• The login and logout functions can take a redirectUrl parameter that specifies a URL to redirect to on completion.
• The login function takes a customInfo parameter that is reserved for future use, and should be set to null.
• We added a get_isLoggedIn method. This method does not contact the server; instead, it is up-to-date with respect to the current component. If you call the login function with no redirectUrl parameter, and if login succeeds, get_isLoggedIn returns true.
• We have removed the verifyUser method.

The following examples show how to authenticate in the RTM release.

var loggedIn = Sys.Services.AuthenticationService.get_isLoggedIn();

Sys.Services.AuthenticationService.login(userLogin, userPassword,
    isPersistentCookie, customInfo, redirectUrl,
    loginCompletedCallback,
    failedCallback, userContext);

Sys.Services.AuthenticationService.logout(redirectUrl,
    logoutCompletedCallback, failedCallback, userContext);

The following example shows the completed callback function signature.

function loginCompleted(validCredentials, userContext, methodName) {..}

The following example shows the failed callback function signature.

function loginFailed(errorObject, userContext, methodName) {..}

The ASP.NET AJAX server framework provides support for component developers writing new server controls and extender controls, as well as for page developers consuming those controls.

The server framework also introduces the UpdatePanel control and other controls that together support incrementally updating an ASP.NET page or Web application with AJAX-type behavior.

The main control in the Server FX is the ScriptManager control and the closely related ScriptManagerProxy control. These controls define an AJAX-style page by delivering and managing the Client FX library scripts.

Beta 2 change: A new script handler that can reduce script size.

Beta 2 breaking change: The new script handler must be registered in the Web.config file.

RC change: The ScriptResource.axd handler can be configured for caching and compression. The handler now also supports the resource substitution logic that is supported by the WebResource.axd handler. You can add substitution references in the embedded Web resources that are then handled by the ScriptResource.axd handler.

Note: The substitution code <%=WebResource() %> inserts a Webresource.axd URL, and the <%= ScriptResource() %> code inserts a ScriptResource.axd URL.

RC breaking change: The script compression module is removed entirely; this is managed entirely by the ScriptResource.axd handler. You must remove the reference in Web.config to the script compression module.

Script compression means that the files are reduced in size, which is done as a result of a request made to the handler. Crunching scripts happens when scripts are built, and removes whitespace and condenses local variable names to further reduce the size of the script files.

In Beta of the RTM release, both debug and release scripts that scripts are handled by ASP.NET are served through a module that compresses them. In Beta 2, this task is managed by the new ScriptResource.axd handler. When static, file-based scripts are referenced, you will need to provide compression through IIS or through some other compression utility is provided.

In Beta 2 of the RTM release, the new ScriptResource.axd handler extracts and serves embedded script libraries and appends the corresponding localized resources as appropriate.

Note: The new script handler is required by the framework and is a breaking change from the previous Beta release. You must register the handler in the Web.config file, as shown in the following example.

By default, the ScriptResource.axd handler caches scripts and compresses scripts where feasible. You can control this behavior by modifying the settings in the Web.config file as demonstrated below.

<system.web>
  <httpHandlers>
    <add verb="GET" path="ScriptResource.axd"
      type="System.Web.Handlers.ScriptResourceHandler,
      System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
      PublicKeyToken=31bf3856ad364e35" validate="false"/>
  </httpHandlers>
</system.web>

<system.web.extensions>
  <scripting>
    ..
    <scriptResourceHandler enableCompression="false"
    enableCaching="false" />
    ..
  </scripting>
</system.web.extensions>

The <system.web.extensions> section also requires the following entry in the Web.config file.

<configSections>
  <sectionGroup name="system.web.extensions"
    type="System.Web.Configuration.SystemWebExtensionsSectionGroup, System.Web.Extensions,
    Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
    <sectionGroup name="scripting" type="System.Web.Configuration.ScriptingSectionGroup,
      System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
      PublicKeyToken=31bf3856ad364e35">
      <section name="scriptResourceHandler"
        type="System.Web.Configuration.ScriptingScriptResourceHandlerSection,
        System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
        PublicKeyToken=31bf3856ad364e35" requirePermission="false"/>
    <sectionGroup name="webServices"
        type="System.Web.Configuration.ScriptingWebServicesSectionGroup,
        System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
        PublicKeyToken=31bf3856ad364e35">
      <section name="jsonSerialization"
          type="System.Web.Configuration.ScriptingJsonSerializationSection,
          System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
          PublicKeyToken=31bf3856ad364e35" requirePermission="false" />
      <section name="profileService"
          type="System.Web.Configuration.ScriptingProfileServiceSection,
          System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
          PublicKeyToken=31bf3856ad364e35" requirePermission="false" />
      <section name="authenticationService"
          type="System.Web.Configuration.ScriptingAuthenticationServiceSection,
          System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
          PublicKeyToken=31bf3856ad364e35" requirePermission="false" />
      </sectionGroup>
    </sectionGroup>
  </sectionGroup>
</configSections>

Beta 2 change: Updates to script references have been made to support localization for static, file-based script references.

RC change: Script references have a new property that can be used to control whether the automatic appending of the notification NotifyScriptLoaded script is appended to assembly-based script libraries.