Home > ASP.NET AJAX > Script Resource Tool

ASP.NET Futures (July 2007): Script Resource Extraction Tool

The script resource tool lets you extract script libraries that are embedded in compiled assemblies and create files out of them. You can then create script references in the ScriptManager control that point to the files on disk. There are a number of reasons why you might might prefer to create script references to path-based script libraries. One might be performance. Another is that script files can be served through the Web server (such as IIS), intead of through ASP.NET's script resource handler. By using the ScriptManager control to refer to extracted script libraries, you can override the default behavior of serving the script files as resources through the ScriptResource handler. But you retain the benefits of localization, versioning, and so on.

In ASP.NET AJAX, the script libraries that are served to the client are defined in the final rendered page with markup similar to the following:

<script src="/app/ScriptResource.axd?d=wpbFVDFPDhodt6lwFDn-EkVTmjQWFSuqgs7TMtISmDgjcT&t=633193326102030698" 
  type="text/javascript"></script>

The ScriptManager control in the Web page is responsible for rendering these script definitions. As the example shows, the script reference points to the ASP.NET AJAX script resource handler (scriptresource.axd) to retrieve a script resource. This script resource is embedded in an assembly in the application. In response to this request, the script resource handler produces a traditional script .js file (library). An advantage of managing script references this way is that the script file can be managed as part of an assembly (control or component) that uses the script. An embedded script is easily transportable; it can be serviced if needed; it is automatically cached on the server by the script resource handler; and it is compressed to reduce the size of the response.

Component developers who write ASP.NET AJAX-enabled controls typically embed script libraries in their assemblies. At run time, the control uses methods of the ScriptManager to register its own script references. The ScriptManager control makes sure that any duplicate references are handled correctly. Because this happens at run time, the page developer does not have to explicitly create a script reference (for example, by using ScriptManager control) to the script library in the assembly.

The ScriptManager control lets you define script references either as paths to script libraries on disk or to named script references in assemblies. To provide background information about the use of the script resource extraction tool, the following section discusses how script libraries are embedded in assemblies.

In Visual Studio, you define a script library as an embedded resource by marking the .js file as an Embedded Resource and by adding an assembly attribute in the AssemblyInfo file that references the script library. The following sample shows this.

		
[assembly: NeutralResourcesLanguage("en-US")]

// Script resources attributes. Note that you need to point to the full name of the embedded resource.
[assembly: WebResource("MyProj.ControlBehavior.js", "text/javascript")]
[assembly: WebResource("MyProj.ControlBehavior.debug.js", "text/javascript")]

// Note that you need to point to the full name of the embedded resource and to the full name
// of the embedded script resource, RESX (no extension in this case, as it's a compiled binary)
[assembly: ScriptResource("MyProj.ControlBehavior.js", "MyProj.ControlBehaviorRes", "MyType.Res")]
[assembly: ScriptResource("MyProj.ToggleButtonBehavior.debug.js", "MyProj.ControlBehaviorRes", 
  "MyType.Res")]

The example shows the following attributes:

• NeutralResourcesLanguageAttribute   Defines the UI culture for the main assembly.
• WebResourceAttribute   Refers to the embedded resource or script libary (ControlBehavior.js), but using the full name (MyProjControlBehavior.js) that will result for the embedded binary resource. In Visual Studio this is the file name prefixed with the project name.
• ScriptResourceAttribute   Refers to the embedded resource or script library, but includes a reference to another binary embedded resource (MyProj.ControlBehaviorRes), without the .resources file name extension. This declaration also defines a type name (MyType.Res) that will be used to generate the JSON object from the binary embedded resource.

The binary embedded resource results from .resx files in the library project; this is also the basis for the script library localization model. Satellite assemblies can be created for specific UI cultures, and the ScriptResource handler will handle these.

The script resource extraction tool lets you point at an assembly that contains an embdded script libraries and create copies of those script libraries on disk. The tool can extract script libraries that have been marked with the WebResourceAttribute and whose MIME type is set to text/javascript, application/javascript, or application/x-javascript.

You can find the script resource tool in the ASP.NET Futures (July 2007) installation folder, which by default is in the following location:

%WINDIR%\Program Files\Microsoft ASP.NET\ASP.NET Futures July 2007\v1.2.61025

When the libraries are extracted, they retain their full name (as described previously). The script libraries are placed in a unique location whose path is derived from the originating assembly, the assembly version, the script file version, and the script file name.

This folder convention is recognized by the ScriptManager control. Therefore, after extracting a script library, you can refer it by its full name and by defining the ScriptPath attribute on the control.

You run the tool at the Windows command line by using the following syntax:

extractjsfromassembly -? | [-v] assemblyPath outputPath

You can specify the following switches:

The following example shows how you might use the tool for an assembly named Custom.dll. The tool extracts the script libraries to the root folder named Scripts. The example assumes that the assembly has localized satellite assemblies in various languages. It also assumes that the assembly is marked with the NeutralResourcesLanguageAttribute set to en-US, and that it uses the WebResourceAttribute and ScriptResourceAttribute attributes. The assembly contains the script libraries CustomBehavior.js and CustomBehavior.debug.js. The NeutralResourcesLanguageAttribute attribute must be defined in the main assembly, otherwise the neutral script files might not be extracted.

extractjsfromassembly -v custom.dll scripts

The result of this example might the following:

..\scripts\custom\1.0.0.0\
    custom.custombehavior.js
    custom.custombehavior.debug.js
    custom.custombehavior.fr-FR.js
    custom.custombehavior.fr-FR.debug.js
    custom.custombehavior.ja-JP.js
    custom.custombehavior.ja-JP.debug.js

You can reference the extracted script libraries by setting the ScriptPath property of the ScriptManager control. In a simple example, if you have extracted script libraries from a custom control assembly and are using that control in a Web page, typically the control will register its assembly-embedded script resource with the ScriptManager control. However, after you extract the script library and set the ScriptPath property, the ScriptManager control will instead use the control's known assembly attributes to determine the folder from which to reference the script library.

The following examples show various ways to reference script libraries in the ScriptManager control. All script references will be redirected through the ScriptPath property of the ScriptManager control, unless script references are defined by using the Path property, or unless they are defined with their own IgnoreScriptPath attribute. Note that this behavior applies also to the ASP.NET AJAX Extensions framework script libraries. In specific examples, the ScriptManager control also uses the ScriptMode and EnableScriptLocalization and EnableScriptGlobalization settings to determine the correct script to reference when there are localized scripts.

In the following example, all scripts are referenced referred through the ScriptPath setting of the ScriptManager control.

<asp:ScriptManager runat="server" ID="ScriptManager1" ScriptPath="~/scripts" />

The following example shows how to make a specific embedded script resource in a custom assembly ignore any ScriptPath setting. In this example, the full name of the embedded script resource and of the assembly is required.

<asp:ScriptManager runat="server" ID="ScriptManager1">
  <Scripts>
    <asp:ScriptReference Name="Custom.Controlbehavior.js" Assembly="Custom" IgnoreScriptPath="true"/>
  </Scripts>
</asp:ScriptManager>

In the following example, a specific script uses only the Path property. In this example, the ScriptManager control uses the assembly's possible satellite assemblies to infer the final file name for the path-based script file. This file name might include the UI culture being requested. Because the file is path-based, the reference ignores any ScriptPath setting entirely.

<asp:ScriptManager runat="server" ID="ScriptManager1" ScriptPath="~/scripts" 
  EnableScriptLocalization="true" EnableScriptGlobalization="true" ScriptMode="Release" >
  <Scripts>
    <asp:ScriptReference Name="custom.custombehavior.js" assembly="custom" Path="scripts" />
  </Scripts>
</asp:ScriptManager>

The following example shows how to make the ASP.NET AJAX Extensions script libraries ignore any ScriptPath setting. In the example, only the partial name of the embedded script resource is required. The framework assumes that the ScriptManager control's assembly has a mapping to the embedded script resource's full name.

<asp:ScriptManager runat="server" ID="ScriptManager1" ScriptPath="~/scripts">
  <Scripts>
    <asp:ScriptReference Name="MicrosoftAjax.js" IgnoreScriptPath="true"/>
  </Scripts>
</asp:ScriptManager>