宣告、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