在ASP.NET AJAX中使用應用程式服務和本地化（1）：身份認證組件AuthenticationService

本文來自《ASP.NET AJAX程式設計 第II卷：用戶端Microsoft AJAX Library相關》的第五章《應用程式服務和本地化》。

 

實現使用者管理是幾乎每一個網站都要考慮的問題，ASP.NET 2.0為此特意內建了身份認證應用程式服務，並以統一的方式提供給開發人員。身份認證應用程式服務不但使用起來非常簡單，也在同時提供了足夠靈活的擴充能力。

參考：若想瞭解更多有關ASP.NET 2.0的身份認證服務，請參考這兩篇MSDN文章：《How ASP.NET Security Works 》（http://msdn2.microsoft.com/en-us/library/78d5caaf-055e-41f1-bbde-1b5020775edb.aspx）和《Managing Users by Using Membership 》（http://msdn2.microsoft.com/en-us/library/824c3a24-f0af-427c-a652-0d2d1e9397cd.aspx）。

ASP.NET AJAX架構的身份認證服務能夠與ASP.NET 2.0的身份認證應用程式服務整合起來，並為其提供用戶端的JavaScript調用代理。ASP.NET AJAX用戶端部分身份認證代理的相關功能統一由用戶端AuthenticationService對象提供。

AuthenticationService對象的完全限定名為Sys.Services.AuthenticationService。這是一個單例（Singleton）模式的對象，無須手工建立執行個體即可使用。只要頁面中包含有ScriptManager控制項，我們即可在用戶端直接存取到AuthenticationService對象，進而間接地與伺服器端身份認證服務打交道並使用ASP.NET 2.0提供的身份認證的相關功能，例如使用者登入和登出等——ASP.NET AJAX架構將負責整個非同步通訊的實現細節，就像ASP.NET AJAX非同步通訊層為Web Service產生用戶端代理一樣。

AuthenticationService對象提供了兩個方法：login()和logout()，分別用來實現使用者登入和登出，還暴露出了一系列的常用屬性。下面讓我們逐一介紹：

 

5.1.1 login()方法

login()方法用來將使用者名稱和密碼傳遞到伺服器端進行驗證，並返回是否通過驗證的資訊，如果需要的話，還會設定相應的用戶端Cookie等資訊。調用login()方法的完整文法如下：

Sys.Services.AuthenticationService.login(

    userName,

    password, 

    isPersistent, 

    customInfo, 

    redirectUrl, 

    loginCompletedCallback, 

    failedCallback, 

    userContext

);

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

表5-1 AuthenticationService對象login()方法的參數

1. userName：將要認證的使用者的使用者名稱。
2. password：將要認證的使用者的密碼。
3. isPersistent：布爾值，表示是否保留持久、跨瀏覽器會話的認證資訊。
4. customInfo：保留欄位，可能在將來使用。
5. redirectUrl：驗證成功之後重新導向到的URL，若該參數值為null，則不會發生重新導向。預設值為null。
6. loginCompletedCallback：調用認證服務完成之後的回呼函數。注意，不管使用者是否通過了伺服器端認證，只要認證過程中沒有出現諸如逾時、異常等問題，都會調用該回呼函數。然後，在該回呼函數內可以得到使用者是否通過了此次驗證的資訊。
7. failedCallback：調用認證服務失敗之後的回呼函數。導致失敗的原因可能是網路連接逾時、或是認證服務內部拋出異常等。若是由於使用者提供的使用者名稱和密碼不正確而不能通過驗證，將不會導致調用認證服務失敗，該回呼函數將不會被調用。
8. userContext：隨本次非同步使用者認證調用發送至伺服器端的使用者內容物件。

表5-1中所列出的8個參數中，只有userName、password和isPersistent是必須的。至於loginCompletedCallback和failedCallback參數，如果為AuthenticationService對象設定了預設值的話（將在稍後介紹），也可以省略。

調用認證服務完成之後的回呼函數，即loginCompletedCallback參數所指定的函數的完整的簽名如下（回呼函數及其參數的名稱可以根據需要自行更改）：

function onLoginCompleted(validCredentials, userContext, methodName)

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

1. validCredentials：一個布爾值，表示使用者是否成功通過了驗證。
2. userContext：在調用login()方法時傳遞的使用者內容物件。
3. methodName：調用方法的方法名。

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

function onAuthenticationFailed(error, userContext, methodName)

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

1. error：導致認證服務失敗的異常對象。
2. userContext：在調用login()方法時傳遞的使用者內容物件。
3. methodName：調用方法的方法名。

 

5.1.2 logout()方法

logout()方法用來登出當前已經登入的使用者。調用logout()方法的完整文法如下：

Sys.Services.AuthenticationService.logout(

    redirectUrl, 

    logoutCompletedCallback, 

    failedCallback, 

    userContext

);

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

表5-2 AuthenticationService對象logout()方法的參數

1. redirectUrl：登出成功之後重新導向到的URL，若該參數值為null，則將自動重新導向至當前頁面。預設值為null。
2. logoutCompletedCallback：登出使用者完成之後的回呼函數。
3. failedCallback：登出使用者失敗之後的回呼函數。導致失敗的原因可能是網路連接逾時、或是認證服務內部拋出異常等。
4. userContext：隨本次非同步使用者認證調用發送至伺服器端的使用者內容物件。

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

登出成功之後的回呼函數，即logoutCompletedCallback參數所指定的函數的完整的簽名如下（回呼函數及其參數的名稱可以根據需要自行更改）：

function onLogoutCompleted(validCredentials, userContext, methodName)

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

1. result：目前並沒有使用到該參數，始終為null。
2. userContext：在調用logout()方法時傳遞的使用者內容物件。
3. methodName：調用方法的方法名。

登出使用者失敗之後的回呼函數，即failedCallback參數所指定的函數的完整的簽名如下（回呼函數及其參數的名稱可以根據需要自行更改）：

function onAuthenticationFailed(error, userContext, methodName)

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

1. error：導致認證服務失敗的異常對象。
2. userContext：在調用login()方法時傳遞的使用者內容物件。
3. methodName：調用方法的方法名。

 

5.1.3 常用屬性

除了前面介紹的login()和logout()方法，AuthenticationService對象還提供了幾個經常用到的屬性，如表5-3所示。

表5-3 AuthenticationService對象的常用屬性

1. isLoggedIn：擷取一個布爾值的屬性，表示目前使用者是否已經登入。
2. timeout：擷取或設定認證請求的逾時時間，單位為毫秒。
3. defaultLoginCompletedCallback：擷取或設定預設的調用認證服務完成之後的回呼函數。
4. defaultLogoutCompletedCallback：擷取或設定預設的登出使用者完成之後的回呼函數。
5. defaultFailedCallback：擷取或設定預設的登入/登出失敗之後的回呼函數。

如下代碼示範了設定AuthenticationService對象的timeout屬性：

Sys.Services.AuthenticationService.set_timeout(3000);

若是預先設定了defaultLoginCompletedCallback、defaultLogoutCompletedCallback和defaultFailedCallback屬性，那麼在調用AuthenticationService對象的login()和logout()方法時，即可免去指定各個回呼函數的工作。例如，如下代碼就設定了AuthenticationService的這3個屬性，並定義了相應的預設回呼函數：

Sys.Services.AuthenticationService.set_defaultLoginCompletedCallback(onLoginCompleted);

Sys.Services.AuthenticationService.set_defaultLogoutCompletedCallback(onLogoutCompleted);

Sys.Services.AuthenticationService.set_defaultFailedCallback(onAuthenticationFailed);

function onLoginCompleted(validCredentials, userContext, methodName) {

    // ...

}

function onLogoutCompleted(result, userContext, methodName) {

    // ...

}

function onAuthenticationFailed(error, userContext, methodName) {

    // ...

}

隨後，我們即可直接使用如下代碼進行使用者登入/登出了。其中userName表示使用者名稱，password表示密碼：

Sys.Services.AuthenticationService.login(userName, password, true);

Sys.Services.AuthenticationService.logout();