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
The 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 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 control.
Provide access to ASP.NET authentication, role, and profile application services from client script by registering these services with the control.
The ability of an ASP.NET page to support partial-page rendering is controlled by the following factors:
The control's EnablePartialRendering property must be true (the default value).
There must be at least one UpdatePanel control on the page.
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 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 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 control in its hierarchy. To register services and scripts for nested pages, user controls, or components when the parent page already has a control, use the ScriptManagerProxy control. For more information, see Using the ASP.NET UpdatePanel Control with Master Pages
Script Management and Registration Overview
The control enables you to register script that is then rendered as part of the page. The 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.
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 control.
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.
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 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.
The 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 control retrieves localized resources (such as localized strings) for the current culture, if they exist. The control provides the following functionality for using localized resources:
Script files that are embedded in an assembly. The 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).
In debug mode. The 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.
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 control.
Enabling Partial-Page Updates
The following example shows how to use the 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
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.
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.