Dynamically Assigning Script References
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.
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
If you do not know the ID of the <asp:ScriptManager> element on the page, call the ScriptManagerGetCurrent() 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.");
Create a ScriptReference object.
Dim SRef As ScriptReference SRef = New ScriptReference()
ScriptReference SRef = new ScriptReference();
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";
SRef.Name = "Script.js" SRef.Assembly = "ScriptAssembly"
SRef.Name = "Script.js"; SRef.Assembly = "ScriptAssembly";
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.
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.