宣告、Azure 與 SharePoint 整合工具組第 4 部分
宣告、Azure 與 SharePoint 整合工具組第 4 部分
這是 CASI (宣告、Azure 與 SharePoint 整合) 套件的第 4 部分 (共 5 個部分)。 第 1 部分： 是整個架構與解決方案的簡介，並說明此系列嘗試執行和涵蓋的內容。 第 2 部分： 包含建立 WCF 應用程式以及使其成為宣告感知，然後將它們移到 Windows Azure 的指示。 第 3 部分： 將新的自訂控制項新增至 _layouts 目錄中的網頁以逐步解說基礎類別，您將使用此基礎類別連接至含 Azure 資料的 SharePoint 網站。 在本篇文章中，我將說明此架構的網頁組件。 它的作用在於與您在第 3 部分建立且新增至版面配置頁面的自訂控制項搭配使用。
使用網頁組件
開始使用網頁組件之前，會假設您 a) 已在 Windows Azure 裝載的可運作 WCF 服務 b) 您已經建立自訂控制項並將它新增至版面配置頁面，如本系列的第 3 部分所述。 我會進一步假設您已將 CASI 套件基礎類別組件及自訂控制項組件部署至 SharePoint 伺服器陣列中每台伺服器上的 GAC。 我也會假設您已經將裝載自訂控制項的自訂 aspx 網頁，部署到伺服器陣列中每台前端伺服器上的版面配置目錄。 我將使用我上傳並附加至第 3 部分文章的 AzureWcfPage 範例專案來說明使用網頁組件的方式。 現在讓我們逐步解說如何將這兩個事件繫結在一起以轉譯 SharePoint 網站中的 Azure。
附註： 雖然不一定要使用網頁組件，但如果呼叫的 WCF 方法傳回 HTML，那麼使用網頁組件可以直接顯示在網頁中，不必進一步處理。
第一個步驟是將 AzureRender.wsp 解決方案部署到伺服器陣列；wsp 包括在附加至此文章的 zip 檔案中。 它包含將 Azure DataView WebPart 以及 jQuery 1.4.2 部署至版面配置目錄的功能。 部署解決方案以及為網站集合啟用功能後，即可將網站組件新增至網頁。 此時，您幾乎可以準備開始從 Azure 轉譯資料，但是您至少需要設定一個屬性。 因此，接下來讓我們逐步說明網頁組件適用的屬性及其他屬性。
網頁組件屬性
所有的網頁組件屬性都位於 [連線內容] 區段中。 最低限度，您需要在您建立和部署的版面配置頁面設定 Data Page 屬性。 例如，/_layouts/AzureData.aspx。 如果自訂控制項的伺服器標籤至少定義了 WcfUrl 與 MethodName 屬性，那麼這樣就夠了。 如果您不執行其他作業，網頁組件將會呼叫網頁並使用網頁中設定的 WCF 端點與方法，它會取得任何方法傳回的資料 (表面上以 HTML 格式傳回)，然後在網頁組件中加以轉譯。 在大多數情況下，部分網頁組件屬性可提供較大的彈性，以下將說明每個屬性：
· 方法名稱* – 應該呼叫的 WCF 應用程式方法名稱。 如果您需要使用自訂的 Javascript 函數呼叫版面配置頁面，則此屬性的查詢字串參數是 “methodname”。
· 參數清單* – WCF 方法的參數清單 (以分號分隔)。 如本系列第 2 部分和第 3 部分中的說明，只支援基本的資料類型 – string、int、bool、long 和 datetime。 如果您需要更複雜的資料類型，應該先將它還原序列化成字串，然後再呼叫方法，接著在 WCF 端點中將它序列化回複雜類型。 如果您需要使用自訂的 Javascript 函數來呼叫版面配置頁面，則此屬性的查詢字串參數是 “methodparams”。
· 成功回呼位址 – 版面配置頁面 jQuery 要求成功完成後回呼的 Javascript 函數。 根據預設，此屬性會使用網頁組件隨附的 Javascript 函數。 如果您使用自己的函數，函數簽章應該如下所示： function yourFunctionName(resultData, resultCode, queryObject). 如需詳細資訊，請參閱 jQuery AJAX 文件，網址： https://api.jquery.com/jQuery.ajax/ (可能為英文網頁)。
· 錯誤回呼位址 – 版面配置頁面 jQuery 要求發生錯誤時回呼的 Javascript 函數。 根據預設，此屬性會使用網頁組件隨附的 Javascript 函數。 如果您使用自己的函數，函數簽章應該如下所示： function yourFunctionName(XMLHttpRequest, textStatus, errorThrown). 如需詳細資訊，請參閱 jQuery AJAX 文件，網址： https://api.jquery.com/jQuery.ajax/ (可能為英文網頁)。
· 標準錯誤訊息 – 網頁組件的伺服器端處理期間發生錯誤時，將顯示在網頁組件中的訊息。 這表示它「不」包括實際上從 Azure 擷取的資料。
· 拒絕存取訊息* – 這是每次拒絕使用者存取特定方法時，會顯示的「拒絕存取」錯誤訊息。 例如，如本系列第 2 個部分中的說明，既然我們要傳遞使用者的 Token 給 WCF 呼叫，我們可以利用 PrincipalPermission 需求修飾所有方法，例如「此使用者必須隸屬於 Sales Managers」群組。 如果使用者不符合 PrincipalPermission 需求，WCF 呼叫將因拒絕存取錯誤而失敗。 在此情況下，網頁組件將會顯示「拒絕存取」訊息所有的內容。 請注意，您可以在此訊息中透過 HTML 標籤使用豐富的格式設定，例如將字型設為粗體或紅色 (亦即 <font color='red'>您沒有存取權，請連絡您的系統管理員</font>)。 如果您需要使用自訂的 Javascript 函數來呼叫版面配置頁面，則此屬性的查詢字串參數是 “accessdenied”。
· 逾時訊息* – 執行 WCF 方法呼叫發生逾時錯誤時會顯示的訊息。 它也支援豐富的格式設定，例如將字型設為粗體、紅色等等。 如果您需要使用自訂的 Javascript 函數來呼叫版面配置頁面，則此屬性的查詢字串參數是“timeout”。
· 顯示重新整理連結 – 核取此方塊以便在 Azure 資料結果上方轉譯重新整理圖示。 如果核取圖示，它將重新執行 WCF 方法以取得最新的資料。
· 重新整理樣式 – 可讓您將其他樣式屬性新增至顯示重新整理連結 IMG 標籤上的 Style 屬性。 例如，您可以使用此屬性新增 “float:right;” ，讓重新整理圖像靠右對齊。
· 快取結果 – 核取此方塊以便讓 jQuery 程式庫快取查詢結果。 這表示每次網頁載入它時將會使用查詢結果的快取版本。 這可省下來回往返 Azure 的時間，從而讓使用者獲得較快的效能。 如果正在擷取的資料不常變更，則使用快取結果是非常好的選擇。
· 解碼結果* – 萬一 WCF 應用程式傳回的結果是 HtmlEncoded，請核取此方塊。 如果您將此屬性設定為 True，則會將 HtmlDecoding 套用至結果。 在大多數情況下，這是不必要的。 如果您需要使用自訂的 Javascript 函數來呼叫版面配置頁面，則此屬性的查詢字串參數是 “encode”。
* – 如果將自訂控制項的 AllowQueryStringOverride 屬性設定為 False，將會忽略這些屬性。
典型使用案例
假設您的 WCF 方法傳回 HTML，在大多數情況下您將新增網頁組件至網頁，然後設定兩個或三個屬性： 資料頁，方法名稱，有時需要設定參數清單。
如果您要進一步顯示和處理 Azure 傳回的資料，您可能會想要使用自訂 Javascript。 在此情況下，您應該將 Javascript 新增至網頁，並將 [成功回呼位址] 屬性設定為您 Javascript 函數的名稱。 如果您的組件需要再回到 WCF 應用程式進行其他張貼動作，例如新增、更新或刪除等動作，您應該新增該功能至自訂 Javascript 功能，並以適當的「方法名稱」與「參數清單」值來呼叫自訂版面配置頁面；要使用的查詢字串變數名稱如上所示。 叫用 jQuery 中的 ajax 方法呼叫版面配置頁面時，您應該使用與網頁組件類似的方法。 它使用的呼叫慣例將以下方的指令碼函數為根據；請注意，您可以繼續使用顯示的 dataFilter 屬性，因為它會去除所有「不是」來自 WCF 方法的網頁輸出：
$.ajax({
type: "GET",
url: "/_layouts/SomePage.aspx",
dataType: "text",
data: "methodname=GetCustomerByEmail&methodparams=steve@contoso.local",
dataFilter: AZUREWCF_azureFilterResults,
success: yourSuccessCallback,
error: yourErrorCallback
});
試試看！
您現在已經萬事具備了，請嘗試建立完整的解決方案吧。 這篇文章所附加的 zip 檔案包括網頁組件的解決方案。 在本系列的下一篇也就是最後的文章中，我將說明如何使用第 2 部分所開發的自訂控制項來擷取 Azure 中的資料，並在 ASP.NET 快取中與其他控制項搭配使用，以及如何在 SharePoint 工作中使用它 – 在此例中，使用的是自訂 SharePoint 計時器工作。
這是翻譯後的部落格文章。英文原文請參閱 The Claims, Azure and SharePoint Integration Toolkit Part 4