To extend your SharePoint site with Microsoft ASP.NET AJAX 1.0, you’ll need to perform a few steps.
First, you will need to download and install ASP.NET AJAX on servers in your farm.
Second, you need to extend web.config with some settings to enable ASP.NET AJAX technology.
Third, you will need to add the ASP.NET AJAX Script Manager into your master page to enable scenarios such as Extenders or UpdatePanels.
Extending SharePoint web.config files with ASP.NET AJAX requires that you interleave some Ajax registration entries in-line with WSS registration entries. To do this you will need to edit your SharePoint web.config file, typically in a directory like c:\inetpub\wwwroot\wss\virtualdirectories\80.
<assemblies>
<add assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
</assemblies>
4. Add some new registrations to the end of the <httpHandlers> section:
<httpHandlers> <add verb="*" path="*.asmx" validate="false" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
<add verb="*" path="*_AppService.axd" validate="false" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
<add verb="GET,HEAD" path="ScriptResource.axd" type="System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" validate="false"/>
</httpHandlers>
5. Add a new registration to the HttpModules section, beneath any existing registrations.
<httpModules>
<add name="ScriptModule" type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
</httpModules>
6. Add a SafeControl entry for the System.Web.UI namespace from Microsoft Ajax Extensions, within the <SharePoint>/<SafeControls>section:
<SafeControls>
<SafeControl Assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" Namespace="System.Web.UI" TypeName="*" Safe="True" />
</SafeControls>
7. Finally, add the following configuration tags at the bottom of web.config, near the bottom before the end <configuration> tag.
<system.web.extensions>
<scripting>
<webServices>
<!-- Uncomment this line to enable the authentication service. Include requireSSL="true" if appropriate. -->
<!--
<authenticationService enabled="true" requireSSL = "true|false"/>
-->
<!-- Uncomment these lines to enable the profile service. To allow profile properties to be retrieved and modified in ASP.NET AJAX applications, you need to add each property name to the readAccessProperties and writeAccessProperties attributes. -->
<!--
<profileService enabled="true"
readAccessProperties="propertyname1,propertyname2"
writeAccessProperties="propertyname1,propertyname2" />
-->
</webServices>
<!--
<scriptResourceHandler enableCompression="true" enableCaching="true" />
-->
</scripting>
</system.web.extensions>
<system.webServer>
<validation validateIntegratedModeConfiguration="false"/>
<modules>
<add name="ScriptModule" preCondition="integratedMode" type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
</modules>
<handlers>
<remove name="WebServiceHandlerFactory-Integrated" />
<add name="ScriptHandlerFactory" verb="*" path="*.asmx" preCondition="integratedMode"
type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
<add name="ScriptHandlerFactoryAppServices" verb="*" path="*_AppService.axd" preCondition="integratedMode" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
<add name="ScriptResource" preCondition="integratedMode" verb="GET,HEAD" path="ScriptResource.axd" type="System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
</handlers>
</system.webServer>
Adding a ScriptManager into a SharePoint MasterPage
Many components of ASP.NET AJAX require the inclusion of a .NET ScriptManager control within a page.
Although it may be possible in some cases to dynamically insert a script manager from within a control, in many cases the control may not be able to insert the script manager early enough in the page lifecycle depending on how the control is used, making this tricky to get right. Also, the control implementer will need to ensure that multiple instances of their control (or other controls) do not result in the addition of multiple script managers within the page. For these reasons, dynamic insertion of a ScriptManager control from another control is not recommended.
To statically embed a script manager into a page, it is recommended that you add the ScriptManager into the master page of a site.
To do this, open up the master page for your site. Typically, this will be located at <site url>/_catalogs/masterpage. You can edit this file by opening it in an editor such as Microsoft SharePoint Designer, or directly in Notepad by opening your master page library via DAV (typically
\\server\<pathtosite>\_catalogs\masterpage.)
Add the following into the markup of your page. A recommended location is right beneath the WebPartManager registration (search for <WebPartPages:SPWebPartManager id="m" runat="Server" />):
<asp:ScriptManager runat="server" ID="ScriptManager1"></asp:ScriptManager>
Using UpdatePanels within SharePoint
UpdatePanels are a very useful addition to ASP.NET AJAX, and represent the simplest way to convert existing, standard ASP.NET controls and parts to take advantage of Ajax techniques. However, there are some changes within Windows SharePoint Services which may get in the way of working with ASP.NET AJAX.
Windows SharePoint Services JavaScript has a “form onSubmit wrapper” which is used to override the default form action. This work is put in place to ensure that certain types of URLs, which may contain double byte characters, will fully work across most postback and asynchronous callback scenarios. However, if your scenarios do not involve double byte character URLs, you may successful disable this workaround and gain the ability to use ASP.NET AJAX UpdatePanels.
To do this, you may need to register a client startup script which disables this workaround, in addition to resetting the default form action:
<script type='text/javascript'>_spOriginalFormAction = document.forms[0].action; _spSuppressFormOnSubmitWrapper=true;</script>
This script may be directly embedded in the page, or could be emitted by a control that uses the UpdatePanel. The following is an example of a very simple ASP.NET Web Part which uses UpdatePanel capabilities:
using System;
using System.Collections;
using System.Text;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI;
namespace MS.Samples
{
public class AjaxUpdatePanelPart : WebPart
{
private Label label;
private TextBox textBox;
protected override void CreateChildControls()
{
base.CreateChildControls();
this.EnsureUpdatePanelFixups();
UpdatePanel up = new UpdatePanel();
up.ID = "UpdatePanel1";
up.ChildrenAsTriggers = true;
up.UpdateMode = UpdatePanelUpdateMode.Conditional;
this.Controls.Add(up);
this.textBox = new TextBox();
this.textBox.ID = "TextBox";
up.ContentTemplateContainer.Controls.Add(this.textBox);
this.label = new Label();
this.label.Text = "Enter your name.";
up.ContentTemplateContainer.Controls.Add(this.label);
Button button = new Button();
button.Text = "Say Hello";
button.Click += new EventHandler(HandleButtonClick);
up.ContentTemplateContainer.Controls.Add(button);
}
private void HandleButtonClick(object sender, EventArgs eventArgs)
{
this.label.Text = "Hello " + this.textBox.Text;
}
private void EnsureUpdatePanelFixups()
{
if (this.Page.Form != null)
{
string formOnSubmitAtt = this.Page.Form.Attributes["onsubmit"];
if (formOnSubmitAtt == "return _spFormOnSubmitWrapper();")
{
this.Page.Form.Attributes["onsubmit"] = "_spFormOnSubmitWrapper();";
}
}
ScriptManager.RegisterStartupScript(this, typeof(AjaxUpdatePanelPart), "UpdatePanelFixup", "_spOriginalFormAction = document.forms[0].action; _spSuppressFormOnSubmitWrapper=true;", true);
}
}
}
Output Caching and ASP.NET AJAX
ASP.NET AJAX infrastructure is not compatible with output caching features. This output caching infrastructure is a featured component of managed content pages such as those supported by web content management features in Microsoft Office SharePoint Server. For this reason, many scenarios which involve output cached features may not be able to take advantage of components like UpdatePanel. However, you will be able to successfully use other ASP.NET AJAX features, such as the JavaScript library, combined with your output cached pages.
Compatibility with output caching is targeted for a future release of ASP.NET AJAX infrastructure.
Conclusion
Microsoft ASP.NET AJAX 1.0 provides great building blocks for building rich Ajax-enabled applications. Combined with the power of the SharePoint platform, and knowing some of the integration limitations, you can build powerful Web2.0 applications that bring together the best of both of these technologies.