ScriptManager Class
Manages ASP.NET AJAX script libraries and script files, partial-page rendering, and client proxy class generation for Web and application services.
Assembly: System.Web.Extensions (in System.Web.Extensions.dll)
[AspNetHostingPermissionAttribute(SecurityAction::InheritanceDemand, Level = AspNetHostingPermissionLevel::Minimal)] [AspNetHostingPermissionAttribute(SecurityAction::LinkDemand, Level = AspNetHostingPermissionLevel::Minimal)] public ref class ScriptManager : public Control, IPostBackDataHandler, IScriptManager
<asp:ScriptManager />
The ScriptManager control is central to AJAX functionality in ASP.NET. The control manages all ASP.NET AJAX resources on a page. This includes downloading Microsoft AJAX Library scripts to the browser and coordinating partial-page updates that are enabled by using UpdatePanel controls. In addition, the ScriptManager control enables you to do the following:
Register script that is compatible with partial-page updates. In order to manage dependencies between your script and the core library, any script that you register is loaded after the Microsoft AJAX Library script.
Specify whether release or debug scripts are sent to the browser.
Provide access to Web service methods from script by registering Web services with the ScriptManager control.
Provide access to ASP.NET authentication, role, and profile application services from client script by registering these services with the ScriptManager control.
Enable culture-specific display of ECMAScript (JavaScript) Date, Number, and String functions in the browser.
Access localization resources for embedded script files or for stand-alone script files by using the ResourceUICultures property of the ScriptReference control.
Register server controls that implement the IExtenderControl or IScriptControl interfaces with the ScriptManager control so that script required by client components and behaviors is rendered.
Partial-Page Rendering
The ability of an ASP.NET page to support partial-page rendering is controlled by the following factors:
The ScriptManager control's EnablePartialRendering property must be true (the default value).
There must be at least one UpdatePanel control on the page.
The SupportsPartialRendering property must be true (the default value). If the SupportsPartialRendering property is not set explicitly, its value is based on browser capabilities.
You can override the value of the EnablePartialRendering property at run time during or before the page's Init event. If you try to change this property after the page's Init event has occurred, an InvalidOperationException exception is thrown.
When partial-page rendering is supported, the ScriptManager control renders script to enable asynchronous postbacks and partial-page updates. The regions of the page to be updated are designated by using UpdatePanel controls. The ScriptManager control handles the asynchronous postbacks and refreshes only the regions of the page that have to be updated. For more information about partial-page rendering, see Partial-Page Rendering Overview. For more information about the conditions that cause an update, see UpdatePanel Control Overview.
Using the ScriptManager Control with Master Pages, User Controls, and Other Child Components
A page can contain only one ScriptManager control in its hierarchy. To register services and scripts for nested pages, user controls, or components when the parent page already has a ScriptManager control, use the ScriptManagerProxy control. For more information, see Using the ASP.NET UpdatePanel Control with Master Pages
Script Management and Registration Overview
The ScriptManager control enables you to register script that is then rendered as part of the page. The ScriptManager control registration methods can be broken into the following three categories:
Registration methods that guarantee that script dependencies on the Microsoft AJAX Library are maintained.
Registration methods that are not dependent on the Microsoft AJAX Library, but that are compatible with UpdatePanel controls.
Registration methods that support working with UpdatePanel controls.
For more information about how to create and use AJAX script in ASP.NET, see Creating Custom Client Script by Using the Microsoft AJAX Library.
Registering Script That Is Dependent on the Microsoft AJAX Library
You can use the following methods to register script files in a way that guarantees that any dependencies on the Microsoft AJAX Library are maintained.
Method | Definition |
|---|---|
Registers a server control that implements the IScriptControl interface that is used to define a Sys.Component client object. The ScriptManager control renders script that supports the client object. | |
Registers a server control that implements the IExtenderControl interface that is used to define a Sys.UI.Behavior client object. The ScriptManager control renders script that supports the client object. |
Registering Partial-Page Update Compatible Scripts
You can use the following methods to register script files that are not dependent on the Microsoft AJAX Library but that are compatible with UpdatePanel controls. These methods correspond to similar methods of the ClientScriptManager control. If you are rendering script for use inside an UpdatePanel control, make sure that you call the methods of the ScriptManager control.
Method | Definition |
|---|---|
Adds a value to a JavaScript array. If the array does not exist, it is created. | |
Renders a script element after the page's opening <form> tag. The script is specified as a string parameter. | |
Renders a script element after the page's opening <form> tag. The script content is specified by setting the src attribute to a URL that points to a script file. | |
Renders a script element after the page's opening <form> tag. The script content is specified with a resource name in an assembly. The src attribute is automatically populated with a URL by a call to an HTTP handler that retrieves the named script from the assembly. | |
Renders a custom name/value attribute pair (an expando) in the markup for a specified control. | |
Renders a hidden field. | |
Registers a script that is executed in response to the form element's submit event. The onSubmit attribute references the specified script. | |
Renders a startup script block just before the page's closing </form> tag. The script to render is specified as a string parameter. |
When you register methods, you specify a type/key pair for that script. If a script with the same type/key pair is already registered, a new script is not registered. Similarly, if you register a script with a type/resource name pair that already exists, the script element that references the resource is not added again. When you register an expando attribute of a previously registered attribute, an exception is thrown. Duplicate registration of array values is allowed.
When you call the RegisterClientScriptInclude or the RegisterClientScriptResource method, avoid registering script that executes inline functions. Instead, register script that contains function definitions like event handlers or custom class definitions for your application.
Registration Methods for UpdatePanel Controls
You can use the following methods to customize partial-page updates when you use UpdatePanel controls.
Method | Definition |
|---|---|
Registers a control as a trigger for asynchronous postbacks. | |
Sends custom data to controls during partial-page rendering. | |
Registers a dispose script for a control that is inside an UpdatePanel control. The script is executed when the UpdatePanel control is updated or deleted. The dispose method is used for client components that are part of the Microsoft AJAX Library and that have to free resources when a component is no longer used. | |
Registers a control as a trigger for a full postback. This method is used for controls inside an UpdatePanel control that would otherwise perform asynchronous postbacks. |
Web Service References
You can register a Web service to be called from client script by creating a ServiceReference object and adding it to the Services collection of the ScriptManager control. ASP.NET generates a client proxy object for each ServiceReference object in the Services collection. You can programmatically add ServiceReference objects to the Services collection to register Web services at run time.
For more information about how to access Web services in script, see Exposing Web Services to Client Script and Calling Web Services from Client Script.
Localization
The ScriptManager control generates references in the rendered page that point to the appropriate localized script files, which are either script files embedded in assemblies or stand-alone script files.
When the EnableScriptLocalization property is set to true, the ScriptManager control retrieves localized resources (such as localized strings) for the current culture, if they exist. The ScriptManager control provides the following functionality for using localized resources:
Script files that are embedded in an assembly. The ScriptManager control determines which culture-specific or fallback-culture script file to send to the browser. It does this by using the culture-specific NeutralResourcesLanguageAttribute assembly attribute, the resources packaged with the assembly, and the UI culture of the browser (if any).
Stand-alone script files. The ScriptManager control defines the list of UI cultures that are supported by using the ResourceUICultures property of the ScriptReference object.
In debug mode. The ScriptManager control tries to render a culture-specific script file that contains debug information. For example, if the page is in debug mode and the current culture is set to en-MX, the control renders a script file that has a name such as scriptname.en-MX.debug.js, if the file exists. If the file does not exist, the debug file for the appropriate fallback culture is rendered
For more information about how to localize resources, see Localizing Resources for Component Libraries Overview.
Error Handling
When a page error occurs during asynchronous postbacks, the AsyncPostBackError event is raised. The way in which errors on the server are sent to the client depends on the AllowCustomErrorsRedirect property, the AsyncPostBackErrorMessage property, and the custom errors section of the Web.config file. For more information, see Customizing Error Handling for ASP.NET UpdatePanel Controls.
The following examples show different scenarios for using the ScriptManager control.
Enabling Partial-Page Updates
The following example shows how to use the ScriptManager control to enable partial-page updates. In this example, a Calendar and a DropDownList control are inside an UpdatePanel control. By default, the value of the UpdateMode property is Always, and the value of the ChildrenAsTriggers property is true. Therefore, child controls of the panel cause an asynchronous postback.
Handling Partial-Page Update Errors and Registering Script
The following example shows how to provide custom error handling during partial-page updates. By default, when an error occurs during partial-page updates, a JavaScript message box is displayed. This example demonstrates how to use custom error handling by providing a handler for the AsyncPostBackError event, and by setting the AsyncPostBackErrorMessage property in the event handler. You can also set the AllowCustomErrorsRedirect property to specify how the custom errors section of the Web.config file is used when an error occurs during partial-page updates. In this example, the default value of the AllowCustomErrorsRedirect property is used. This means that if the Web.config file contains a customErrors element, that element determines how errors are displayed. For more information, see customErrors Element (ASP.NET Settings Schema).
Globalizing the Date and Time That Are Displayed in the Browser
The following example shows how to set the EnableScriptGlobalization property so that client script can display a culture-specific date and time in the browser. In the example, the Culture attribute of the @ Page directive is set to auto. As a result, the first language that is specified in the current browser settings determines the culture and UI culture for the page. For more information, see How to: Set the Culture and UI Culture for ASP.NET Web Page Globalization.
- AspNetHostingPermission
for operating in a hosted environment. Demand value: LinkDemand. Permission value: Minimal.
- AspNetHostingPermission
for operating in a hosted environment. Demand value: InheritanceDemand. Permission value: Minimal.
Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.