【Dflying Chen 】在ASP.NET AJAX中應用程式：使用者個性化元件ProfileService

在內建了身份認證應用程式服務之後，ASP.NET 2.0已經提供了對使用者管理的初步支援。然而，使用者資訊卻不僅僅只是使用者名稱和密碼這兩項，對於一般網站來講，我們都需要提供一些與使用者帳號相關聯的自定義屬性。例如在BBS程式中，這類自定義屬性就有使用者的積分、等級、簽名檔、頭像等，這些自定義屬性都與使用者帳號一一對應。為此，ASP.NET 2.0特意內建了使用者個性化應用程式服務，同樣以統一的方式提供給開發者。ASP.NET 2.0內建的使用者個性化應用程式服務的配置、使用非常簡單，也提供了足夠靈活的擴充套件能力。

參考：若想了解更多有關ASP.NET 2.0的使用者個性化服務，請參考這篇MSDN文章：《ASP.NET Profile Properties 》（http://msdn2.microsoft.com/en-us/library/at64shx3.aspx）。

ASP.NET AJAX框架的使用者個性化服務能夠與ASP.NET 2.0的使用者個性化應用程式服務整合起來，併為其提供客戶端的JavaScript呼叫代理。ASP.NET AJAX客戶端部分使用者個性化代理的相關功能統一由客戶端ProfileService物件提供。

ProfileService物件的完全限定名為Sys.Services.ProfileService。與AuthenticationService物件類似，ProfileService是一個單例（Singleton）模式的物件，無須手工建立例項即可使用。只要頁面中包含有ScriptManager控制元件，我們即可在客戶端直接訪問到ProfileService物件，進而間接地與伺服器端使用者個性化服務打交道並使用ASP.NET 2.0提供的使用者個性化服務的相關功能，例如載入或儲存使用者的個性化屬性等——ASP.NET AJAX框架將負責整個非同步通訊的實現細節，就像ASP.NET AJAX非同步通訊層為Web Service生成客戶端代理一樣。

ProfileService物件提供了兩個方法：load()和save()，分別用來載入和儲存使用者的個性化屬性，還提供了一個名為properties的欄位，用來以類似伺服器端“強型別訪問方式”的方法在客戶端訪問使用者個性化屬性。此外，ProfileService還暴露出了一系列的常用屬性。下面我們來逐一介紹：

5.3.1 load()方法

load()方法用來載入當前使用者的個性化屬性，在載入完成之後，我們即可在客戶端通過ProfileService物件的properties屬性訪問到已經被載入的各個使用者個性化屬性。呼叫load()方法的完整語法如下：

Sys.Services.ProfileService.load(

    propertyNames, 

    loadCompletedCallback, 

    failedCallback, 

    userContext

);

表5-4 ProfileService物件load()方法的引數

1. propertyNames：一個包含string物件的陣列，表示需要從伺服器端載入的使用者個性化屬性集合。若是該引數為null的話，則ASP.NET AJAX將自動載入所有允許客戶端讀取的使用者個性化屬性。關於如何將ASP.NET 2.0中的各個使用者個性化屬性有選擇性地暴露給客戶端，將在本章下一節的示例程式中介紹。
2. loadCompletedCallback：載入使用者個性化屬性完成之後的回撥函式。
3. failedCallback：載入使用者個性化屬性失敗時的回撥函式。導致失敗的原因可能是網路連線超時、或是使用者個性化服務內部丟擲異常等。
4. userContext：隨本次非同步呼叫傳送至伺服器端的使用者上下文物件。

表5-4中所列出的4個引數均為可選。對於loadCompletedCallback和failedCallback引數，如果為ProfileService物件設定了預設值的話（將在稍後介紹），也可以省略。

載入使用者個性化屬性完成之後的回撥函式，即loadCompletedCallback引數所指定的函式的完整的簽名如下（回撥函式及其引數的名稱可以根據需要自行更改）：

function onLoadCompleted(numProperties, userContext, methodName) 

其中，ASP.NET AJAX在執行回撥時為我們提供了3個引數：

1. numProperties：表示此次載入過程中載入了的使用者個性化屬性的個數。
2. userContext：在呼叫load()方法時傳遞的使用者上下文物件。
3. methodName：呼叫方法的方法名。

呼叫認證服務失敗之後的回撥函式，即failedCallback引數所指定的函式的完整的簽名如下（回撥函式及其引數的名稱可以根據需要自行更改）：

function onProfileFailed(error, userContext, methodName) 

ASP.NET AJAX在執行回撥時同樣為我們提供了3個引數：

1. error：導致認證服務失敗的異常物件。
2. userContext：在呼叫load()方法時傳遞的使用者上下文物件。
3. methodName：呼叫方法的方法名。

5.3.2 save()方法

save()方法用來儲存當前可能經過修改的使用者個性化屬性。呼叫save()方法的完整語法如下：

Sys.Services.ProfileService.save(

    propertyNames, 

    saveCompletedCallback, 

    failedCallback, 

    userContext

);

其中各個引數的含義如表5-5所示。

表5-5 ProfileService物件logout()方法的引數

1. propertyNames：一個包含string物件的陣列，表示需要儲存至伺服器的使用者個性化屬性集合。若是該引數為null的話，則ASP.NET AJAX將自動儲存所有允許從客戶端寫入的使用者個性化屬性。關於如何將ASP.NET 2.0中的各個使用者個性化屬性有選擇性地暴露給客戶端，將在本章下一節的示例程式中介紹。
2. saveCompletedCallback：儲存使用者個性化屬性完成之後的回撥函式。
3. failedCallback ：儲存使用者個性化屬性失敗時的回撥函式。導致失敗的原因可能是網路連線超時、或是使用者個性化服務內部丟擲異常等。
4. userContext：隨本次非同步呼叫傳送至伺服器端的使用者上下文物件。

表5-5中所列出的4個引數均是可選的。對於saveCompletedCallback和failedCallback引數，如果為ProfileService物件設定了預設值的話（將在稍後介紹），也可以省略。

儲存使用者個性化屬性完成之後的回撥函式，即saveCompletedCallback引數所指定的函式的完整的簽名如下（回撥函式及其引數的名稱可以根據需要自行更改）：

function onSaveCompleted(numProperties, userContext, methodName) 

其中，ASP.NET AJAX在執行回撥時為我們提供了3個引數：

1. numProperties：表示此次儲存過程中儲存了的使用者個性化屬性的個數。
2. userContext：在呼叫save()方法時傳遞的使用者上下文物件。
3. methodName：呼叫方法的方法名。

儲存使用者個性化屬性失敗時的回撥函式，即failedCallback引數所指定的函式的完整的簽名如下（回撥函式及其引數的名稱可以根據需要自行更改）：

function onProfileFailed(error, userContext, methodName) 

ASP.NET AJAX在執行回撥時同樣為我們提供了3個引數：

1. error：導致認證服務失敗的異常物件。
2. userContext：在呼叫save()方法時傳遞的使用者上下文物件。
3. methodName：呼叫方法的方法名。

5.3.3 properties欄位

ASP.NET 2.0所提供了使用者個性化應用程式服務中的一個非常強大的特性就是，它允許開發者以強型別的方式訪問到各個預定義的使用者個性化屬性。例如，若我們在web.config檔案的\節中定義瞭如下的使用者個性化屬性：  

<profile enabled="true">

  <properties>

    <add name="Address" type="System.String" />

    <add name="Age" type="System.Int32" />

    <add name="InfoPanelPosition" type="System.Drawing.Point" />

  properties>

profile>

那麼在ASP.NET頁面中，即可直接以強型別的方式訪問到這些屬性。請參考如下一段伺服器端C#程式碼：

string address = Profile.Address;

int age = Profile.Age;

System.Drawing.Point infoPanelPosition = Profile.InfoPanelPosition;

雖然在客戶端使用的JavaScript是一門動態語言，其中的變數並沒有那麼“嚴格”的型別約束，不過ProfileService物件所提供的properties欄位依然能夠讓開發者能夠以類似的語法規則在客戶端訪問使用者個性化屬性。

在呼叫ProfileService物件的load()方法，併成功載入了使用者個性化屬性之後，我們即可使用其properties欄位以類似上述C#程式碼的方式在JavaScript中訪問到各個使用者個性化屬性；

var address = 

    Sys.Services.ProfileService.properties.Address;

var age = 

    Sys.Services.ProfileService.properties.Age;

var infoPanelPosition = 

    Sys.Services.ProfileService.properties.InfoPanelPosition;

ProfileService物件的properties欄位也能夠支援web.config檔案中定義的使用者個性化組（Profile Group）。例如如下使用者個性化組的定義：

<profile enabled="true">

  <properties>

    <group name="Address">

      <add name="Street" type="System.String" />

      <add name="City" type="System.String"/>

      <add name="PostalCode" type="System.String" />

    group>

  properties>

profile>

在客戶端JavaScript中，我們也可以使用如下的語法（即[GroupName].[PropertyName]）對這個使用者個性化組中的屬性進行訪問：

var street = 

    Sys.Services.ProfileService.properties.Address.Street;

var city = 

    Sys.Services.ProfileService.properties.Address.City;

var postCode = 

    Sys.Services.ProfileService.properties.Address.PostCode;

5.3.4 常用屬性

除了前面介紹的load()、save()方法以及properties屬性之外，ProfileService物件還提供了幾個經常用到的屬性，如表5-6所示。

表5-6 ProfileService物件的常用屬性

1. timeout：獲取或設定載入/儲存使用者個性化屬性的超時時間，單位為毫秒。
2. defaultLoadCompletedCallback ：獲取或設定預設的載入使用者個性化屬性完成之後的回撥函式。
3. defaultSaveCompletedCallback：獲取或設定預設的儲存使用者個性化屬性完成之後的回撥函式。
4. defaultFailedCallback：獲取或設定預設的載入/儲存使用者個性化屬性失敗時的回撥函式。

如下程式碼演示了設定ProfileService物件的timeout屬性：

Sys.Services.ProfileService.set_timeout(3000); 

若是預先設定了defaultLoadCompletedCallback、defaultSaveCompletedCallback和defaultFailedCallback屬性，那麼在呼叫ProfileService物件的load()和save()方法時，即可不必重複指定各個回撥函式。例如，如下程式碼就設定了ProfileService物件的這3個屬性，並定義了相應的預設回撥函式：

Sys.Services.ProfileService.set_defaultLoadCompletedCallback(onLoadCompleted);

Sys.Services.ProfileService.set_defaultSaveCompletedCallback(onSaveCompleted);

Sys.Services.ProfileService.set_defaultFailedCallback(onProfileFailed);

function onLoadCompleted(numProperties, userContext, methodName) {

    // ...

}

function onSaveCompleted(numProperties, userContext, methodName) {

    // ...

}

function onProfileFailed(error, userContext, methodName) {

    // ...

}

隨後，我們即可直接使用如下程式碼載入/儲存使用者的個性化屬性了，是不是顯得非常簡單呢？

Sys.Services.ProfileService.load();

Sys.Services.ProfileService.save();

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/12639172/viewspace-343326/，如需轉載，請註明出處，否則將追究法律責任。