本文整理自多處公開資料,作為個人知識管理之用,無法逐一列出出處,特此說明。
Windows SharePoint Services v3 建構在 ASP.NET 2.0 之上,而 Microsoft ASP.NET AJAX 1.0 是在 MOSS 之後才推出,因此兩者在某些情況下會有相容性問題;這些問題在 WSS 的 SP1 中獲得解決。在此之前,若要在 SharePoint 中使用 ASP.NET AJAX,必須額外做一些部署步驟。
兩個先決限制:
第一步,下載並在 Web 前端伺服器上安裝 ASP.NET 2.0 AJAX Extensions 1.0(可自 AJAX ASP.NET 官方網站取得)。
第二步,擴充 SharePoint 的 web.config。該檔案通常位於:
c:\inetpub\wwwroot\wss\VirtualDirectories\80
在 <configSections> 中加入 <sectionGroup>:
<configSections>
<sectionGroup name="system.web.extensions"
type="System.Web.Configuration.SystemWebExtensionsSectionGroup,
System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35">
<sectionGroup name="scripting"
type="System.Web.Configuration.ScriptingSectionGroup,
System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35">
<section name="scriptResourceHandler"
type="System.Web.Configuration.ScriptingScriptResourceHandlerSection,
System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"
requirePermission="false" allowDefinition="MachineToApplication"/>
<sectionGroup name="webServices"
type="System.Web.Configuration.ScriptingWebServicesSectionGroup,
System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35">
<section name="jsonSerialization"
type="System.Web.Configuration.ScriptingJsonSerializationSection,
System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"
requirePermission="false" allowDefinition="Everywhere" />
<section name="profileService"
type="System.Web.Configuration.ScriptingProfileServiceSection,
System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"
requirePermission="false" allowDefinition="MachineToApplication" />
<section name="authenticationService"
type="System.Web.Configuration.ScriptingAuthenticationServiceSection,
System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"
requirePermission="false" allowDefinition="MachineToApplication" />
</sectionGroup>
</sectionGroup>
</sectionGroup>
</configSections>
在 <system.web>/<pages> 中加入控制項前綴:
<pages>
<controls>
<add tagPrefix="asp" namespace="System.Web.UI"
assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"/>
</controls>
</pages>
在 <compilation> 的 <assemblies> 中加入組件:
<assemblies>
<add assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"/>
</assemblies>
在 <httpHandlers> 中加入:
<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>
在 <httpModules> 末尾註冊 ScriptModule:
<httpModules>
<add name="ScriptModule"
type="System.Web.Handlers.ScriptModule, System.Web.Extensions,
Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"/>
</httpModules>
在 <SharePoint>/<SafeControls> 中加入一條 SafeControl,否則 SharePoint 會阻擋 System.Web.UI 命名空間下的控制項:
<SafeControls>
<SafeControl Assembly="System.Web.Extensions, Version=1.0.61025.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35"
Namespace="System.Web.UI" TypeName="*" Safe="True" />
</SafeControls>
最後,在 </configuration> 之前加入:
<system.web.extensions>
<scripting>
<webServices>
<!-- 取消註解即可啟用 authentication service,必要時加上 requireSSL="true" -->
<!--
<authenticationService enabled="true" requireSSL="true"/>
-->
<!-- 取消註解即可啟用 profile service;
欲讓 AJAX 應用讀寫設定屬性,需把屬性名列進
readAccessProperties 與 writeAccessProperties -->
<!--
<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>
撰寫支援 AJAX 的 WebPart 最省事的做法,是繼承一個已經處理好 ScriptManager 的基底類別。這個基底類別主要負責三件事:確保頁面上存在並正確設定 ScriptManager、修正 SharePoint 表單 onsubmit 與回傳的衝突、以及提供統一的錯誤顯示機制。
using System;
using System.Web;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.Script.Serialization;
using System.Xml.Serialization;
using Microsoft.SharePoint.Utilities;
/// <summary>
/// 在 WSS 中使用 ASP.NET AJAX 擴充所需的基底類別
/// </summary>
[XmlRoot(Namespace = "Deps.AjaxBaseWebpart")]
public abstract class AjaxBaseWebpart : Microsoft.SharePoint.WebPartPages.WebPart
{
private string _validationGroupId;
private ValidationSummary _errorContainer;
private ScriptManager _ajaxManager;
public AjaxBaseWebpart() { }
/// <summary>以統一方式向使用者顯示錯誤</summary>
public void RegisterError(string message)
{
if (this.Controls.Contains(_errorContainer))
{
// 產生唯一控制項 ID 的做法,取自部分內建 WebPart
int uniqueCounter;
if (HttpContext.Current.Items["GetUniqueControlId"] != null)
uniqueCounter = (int)HttpContext.Current.Items["GetUniqueControlId"];
else
uniqueCounter = 0;
uniqueCounter++;
HttpContext.Current.Items["GetUniqueControlId"] = uniqueCounter;
// 用 CustomValidator 把錯誤登進 ValidationSummary
CustomValidator cv = new CustomValidator();
cv.ID = string.Concat("_Error_", uniqueCounter);
cv.ValidationGroup = _validationGroupId;
cv.Display = ValidatorDisplay.None;
cv.IsValid = false;
cv.ErrorMessage = message;
this.Controls.Add(cv);
}
else
{
// 若在 CreateChildControls 之前呼叫 RegisterError,導向錯誤頁
SPUtility.TransferToErrorPage(
"AjaxBaseWebpart 的 CreateChildControls 尚未執行。" +
"請在您的 CreateChildControls 覆寫最上方加上 base.CreateChildControls();");
}
}
/// <summary>
/// 必須呼叫,以確保 ValidationSummary 已註冊到頁面。
/// 任何衍生 WebPart 都應在 CreateChildControls 覆寫最上方呼叫它。
/// </summary>
protected override void CreateChildControls()
{
base.CreateChildControls();
if (!this.Controls.Contains(_errorContainer))
{
_validationGroupId = Guid.NewGuid().ToString();
_errorContainer = new ValidationSummary();
_errorContainer.ID = "_errorContainer";
_errorContainer.ValidationGroup = _validationGroupId;
_errorContainer.BorderStyle = BorderStyle.Solid;
_errorContainer.BorderWidth = Unit.Pixel(3);
_errorContainer.BorderColor = Color.Red;
this.Controls.Add(_errorContainer);
}
}
/// <summary>
/// OnInit 早於頁面載入,支援 AJAX 所需的頁面調整都在此進行。
/// </summary>
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
// 先嘗試取得頁面上既有的 ScriptManager
_ajaxManager = ScriptManager.GetCurrent(this.Page);
if (_ajaxManager == null)
{
// 沒有就自建,並啟用部分渲染
_ajaxManager = new ScriptManager();
_ajaxManager.EnablePartialRendering = true;
// 修正回傳與表單 action 的問題
Page.ClientScript.RegisterStartupScript(typeof(AjaxBaseWebpart), this.ID,
"_spOriginalFormAction = document.forms[0].action;", true);
// SharePoint 的表單掛了 onsubmit="return _spFormOnSubmitWrapper();",
// 它會在第一次之後攔掉後續的非同步回傳。
// 改為不 return,讓 AJAX 擴充能正常運作。
if (this.Page.Form != null)
{
string formOnSubmitAtt = this.Page.Form.Attributes["onsubmit"];
if (!string.IsNullOrEmpty(formOnSubmitAtt) &&
formOnSubmitAtt == "return _spFormOnSubmitWrapper();")
{
this.Page.Form.Attributes["onsubmit"] = "_spFormOnSubmitWrapper();";
}
// 把 ScriptManager 放在表單的第一個控制項
this.Page.Form.Controls.AddAt(0, _ajaxManager);
}
}
}
/// <summary>頁面目前的 ScriptManager,OnInit 之後才有值</summary>
[WebPartStorage(Storage.None)]
public ScriptManager AjaxManager
{
get { return _ajaxManager; }
set { _ajaxManager = value; }
}
}
開發時只要繼承這個類別,就能在裡面放 UpdatePanel 與其他控制項,不必每個 WebPart 都自己處理 ScriptManager 的註冊與 SharePoint 表單的相容問題。
上述 onsubmit 的處理本質上是一種 hack:它讓 SharePoint 原本用來阻擋重複回傳的包裝失效,換取 AJAX 擴充正常運作。若你的 WebPart 不需要連續多次回傳,這是可行的折衷,但要在註解中留下說明,以免後人誤刪。此外,SafeControl 設定若漏掉,控制項會在 SharePoint 上被直接封鎖,這是部署後「頁面一片空白」的常見原因,值得優先檢查。