Dynamically Assigning Script References

  • Artikel

In most scenarios, the easiest way to add a script file to an ASP.NET page is in markup, as in the following example:

<asp:ScriptManager ID="SMgr" runat="server">
  <Scripts>
    <asp:ScriptReference Path="./Script.js" />
  </Scripts>
</asp:ScriptManager>

However, it is also possible to add script references dynamically. Page developers can do this to have more control over how a script is added. For example, they might add scripts dynamically to help conserve memory resources by not loading a large script library unless it is needed. Or they might load different versions of scripts for different types of users. Control developers add scripts dynamically when they create script controls or extender controls in order to make script resources automatically available to the page that hosts the control.

This topic addresses a simple page developer scenario. For adding script references in custom controls, see Creating an Extender Control to Associate a Client Behavior with a Web Server Control.

Script references can specify script files or scripts embedded as resources in assemblies. Scripts can exist in debug and retail versions. The following procedure shows how to assign a script reference to a page in each of these situations.

Note

All script files to be registered with the ScriptManager control must call the notifyScriptLoaded method to notify the application that the script has finished loading. Assembly-based scripts should not call this method in most cases. For more information, see Sys.Application.notifyScriptLoaded Method.

To dynamically add a script reference to a page

  1. If you do not know the ID of the <asp:ScriptManager> element on the page, call the ScriptManager.GetCurrent method of the ScriptManager control to get the current instance of the control. Test for null in case there is no ScriptManager control on the page. If you know that there is an <asp:ScriptManager> element on the page and you know its ID value, you can skip this step.

    The following example shows how to test for the existence of a ScriptManager control on a page, and then either get the current instance or create a new instance.

    ' If there is a ScriptManager on the page, use it.
' If not, throw an exception.
Dim SMgr As ScriptManager
If ScriptManager.GetCurrent(Page) Is Nothing Then
    Throw New Exception("ScriptManager not found.")
Else : SMgr = ScriptManager.GetCurrent(Page)
End If

    // If there is a ScriptManager on the page, use it.
// If not, throw an exception.
ScriptManager Smgr = ScriptManager.GetCurrent(Page);
if (Smgr == null) throw new Exception("ScriptManager not found.");

  2. Create a ScriptReference object.

    Dim SRef As ScriptReference
SRef = New ScriptReference()

    ScriptReference SRef = new ScriptReference();

  3. For file-based scripts, if you know that the ScriptPath property of the ScriptManager control is set to the correct location for the script file, set the Name property of the ScriptReference instance to the name of the script file. Otherwise, set the Path property of the ScriptReference object to the absolute, relative, or application-relative URL of the script file to add.

    ' If you know that Smgr.ScriptPath is correct...
SRef.Name = "Script.js"

' Or, to specify an app-relative path...
SRef.Path = "~/Scripts/Script.js"

    // If you know that Smgr.ScriptPath is correct...
SRef.Name = "Script.js";

// Or, to specify an app-relative path...
SRef.Path = "~/Scripts/Script.js";

  4. If the script is part of an assembly, set the Name and Assembly properties of the ScriptReference instance.

    SRef.Name = "Script.js"
SRef.Assembly = "ScriptAssembly"

    SRef.Name = "Script.js";
SRef.Assembly = "ScriptAssembly";

  5. Specify whether to run debug or release versions of the script. To set this mode for all scripts on the page, set the ScriptMode property of the ScriptManager control. To set debug mode for an individual script, set the ScriptMode property of the ScriptReference object.

    The following example demonstrates both options.

    ' To set ScriptMode for all scripts on the page...
SMgr.ScriptMode = ScriptMode.Release

'Or, set ScriptMode for just for the one script...
SRef.ScriptMode = ScriptMode.Debug

'If they conflict, the setting on the ScriptReference wins.

    // To set ScriptMode for all scripts on the page...
Smgr.ScriptMode = ScriptMode.Release;

//Or, to set the ScriptMode just for the one script...
SRef.ScriptMode = ScriptMode.Debug;

//If they conflict, the setting on the ScriptReference wins.

    Note

    If the Path property of the ScriptReference object is not set, the ScriptMode property of the ScriptManager control is set to Release by default. If the Path property of the ScriptReference object is set, the ScriptManager control looks for both debug and release scripts unless its ScriptMode property is set to a specific mode.

  6. Add the ScriptReference object to the Scripts collection of the ScriptManager control.

    SMgr.Scripts.Add(SRef)

    Smgr.Scripts.Add(SRef);

See Also

Reference

ScriptReference

ScriptManager

ScriptMode

Concepts

ASP.NET Client Script

Client Script in ASP.NET Web Pages

Creating an Extender Control to Associate a Client Behavior with a Web Server Control

Adding Client Capabilities to a Web Server Control