Goal of this post
This post aims at providing the most flexible and convenient way to make sure that a valid ScriptManager is available on page when you develop WebParts dealing with AJAX for ASP.net or Silverlight controls.
Problematic overview
ScriptManager is the key object making Silverlight and AJAX for ASP.net controls run on your ASP.net page. This non-visual control basically aims at loading JS scripts relevant for those technologies. Referring to MS documentation, it must appear as the first control in page controls tree in order to be available for any control requiring AJAX support. A ScriptManager can be embedded either from markup code of the hosting page, or programmatically during page lifecycle.
So let’s imagine you are developing a WebPart embedding a Silverlight application. You want to redistribute this WebPart but you don’t want users to modify anything in their SharePoint portal to make it run. Basically, in your code, you will try to see if a ScriptManager is present on the page and if no you will add it on the fly.
Then you have to face several issues:
- Where can I place my ScriptManager in the controls tree to make it available to relevant controls?
- Which event do I need to choose to attach my code?
- Will it be compliant with postback events, databinding cycles and WebParts connection management?
Solution
First, you need to add a new ScriptManager as the first control in the page form. Before adding anything, you have to ensure that no ScriptManager is already present on the page.
if (Page != null && ScriptManager.GetCurrent(Page) == null)
{
Page.Form.Controls.AddAt(0, new ScriptManager());
}Then you need to determine where to place this code to be compliant with requirements evoked at question #3. The most reliable answer is to override the OnInit event of your WebPart and paste your code there
protected override void OnInit(EventArgs e)
{
if (Page != null && ScriptManager.GetCurrent(Page) == null)
{
Page.Form.Controls.AddAt(0, new ScriptManager());
}
base.OnInit(e);
}An alternative approach could be to attach a handler to the page LoadComplete event, but it gives no gain to the previous solution.
Common errors
I’ve listed below some common mistakes and the corresponding errors when trying to answer to questions above.
Do not add control directly to Page’s controls collection; add it to its Form property.
Page.Controls.AddAt(0, new ScriptManager());
Page.Form.Controls.AddAt(0, new ScriptManager());
Striked code above will produce the following error
Control 'ctl01' of type 'ScriptManager' must be placed inside a form tag with runat=server
If so, you will receive the error below
The control collection cannot be modified during DataBind, Init, Load, PreRender or Unload phases.
Web parts lifecycle is too restrictive to use this approach.
- If you try to attach a handler to the Page Init event, your code will never be executed because Web parts are added after the page InitComplete event.
- If you try to attach a handler to the Page Load or PreLoad events, your code will never be executed when your Web part is being added to the page and you will receive the error below (next attempts will work). The fact is that when a Web part is added to a page, any page event prior to LoadComplete is ignored.
The control with ID 'XXX' requires a ScriptManager on the page. The ScriptManager must appear before any controls that need it.
- If you try to attach a handler to the Page PreRender event, you will receive the error below
Script controls may not be registered before PreRender.