實作設定檔提供者

發行項
10/22/2014

更新：2007 年 11 月

ASP.NET 設定檔功能可讓您輕鬆地使用不同的提供者。例如使用 .NET Framework 所提供的 SqlProfileProvider 類別，或是實作自己的提供者。

如有下列需要時，可以建立自訂設定檔提供者：

設定檔資訊必須儲存在如 FoxPro 資料庫或 Oracle 資料庫等的資料來源，但是這些資料來源不受隨附於 .NET Framework 之設定檔提供者的支援。
管理設定檔資訊時所需要使用的資料庫結構描述，與 .NET Framework 隨附之提供者所使用的資料庫結構描述不同。常見的情況是您想要將設定檔資訊與現有 SQL Server 資料庫中的使用者資料進行整合。

必要的類別

若要實作設定檔提供者，請建立繼承 System.Web.Profile.ProfileProvider 抽象類別的類別。而 ProfileProvider 抽象類別則是繼承 System.Configuration.SettingsProvider 抽象類別 (其繼承 System.Configuration.Provider.ProviderBase 抽象類別)。因為這種繼承鏈結，所以除了 ProfileProvider 類別的必要成員以外，您也必須實作 SettingsProvider 和 ProviderBase 類別的必要成員。

下表說明 ProviderBase、SettingsProvider 和 ProfileProvider 抽象類別中需要實作的屬性和方法。若要重新檢視每個成員的實作，請參閱 HOW TO：建置並執行設定檔提供者範例。

ProviderBase 成員

成員	說明
Initialize 方法	以提供者執行個體名稱和組態設定的 NameValueCollection 做為輸入參數。這個方法會用來設定提供者執行個體的選項和屬性值，包括實作特定值以及電腦組態檔或 Web.config 檔中指定的選項。

SettingsProvider 成員

成員	說明
ApplicationName 屬性	儲存在每個設定檔中的應用程式名稱。設定檔提供者會使用應用程式名稱，為每個應用程式儲存不同的設定檔資訊。如果在不同的應用程式中建立相同的使用者名稱，這能夠讓多個 ASP.NET 應用程式在不發生衝突的情況下，使用相同的資料來源。此外，多個 ASP.NET 應用程式也可以藉由指定相同的應用程式名稱，共用設定檔資料來源。
GetPropertyValues 方法	以 SettingsContext 和 SettingsPropertyCollection 物件做為輸入參數。 SettingsContext 會提供使用者資訊。您可以使用資訊做為主索引鍵，以擷取使用者的設定檔屬性資訊。請使用 SettingsContext 物件取得使用者名稱，以及判斷使用者是經過驗證還是匿名。 SettingsPropertyCollection 包含 SettingsProperty 物件的集合。每個 SettingsProperty 物件會提供屬性的名稱和型別，以及像是屬性預設值和屬性是否唯讀的其他資訊。GetPropertyValues 會根據提供做為輸入的 SettingsProperty 物件，使用 SettingsPropertyValue 物件填入 SettingsPropertyValueCollection。將指定使用者之資料來源所提供的值，指派給每個 SettingsPropertyValue 物件的 PropertyValue 屬性，然後傳回整個集合。呼叫此方法也會將指定使用者設定檔的 LastActivityDate 值，更新為目前的日期和時間。
SetPropertyValues 方法	以 SettingsContext 和 SettingsPropertyValueCollection 物件做為輸入參數。 SettingsContext 會提供使用者資訊。您可以使用資訊做為主索引鍵，以擷取使用者的設定檔屬性資訊。請使用 SettingsContext 物件取得使用者名稱，以及判斷使用者是經過驗證還是匿名。 The SettingsPropertyValueCollection 包含 SettingsPropertyValue 物件的集合。每個 SettingsPropertyValue 物件會提供屬性的名稱、型別和值，以及像是屬性預設值和屬性是否唯讀的其他資訊。SetPropertyValues 方法會更新指定使用者之資料來源中的設定檔屬性值。呼叫方法也會將指定使用者設定檔的 LastActivityDate 和 LastUpdatedDate 值，更新為目前的日期和時間。

ApplicationName 屬性

儲存在每個設定檔中的應用程式名稱。設定檔提供者會使用應用程式名稱，為每個應用程式儲存不同的設定檔資訊。如果在不同的應用程式中建立相同的使用者名稱，這能夠讓多個 ASP.NET 應用程式在不發生衝突的情況下，使用相同的資料來源。此外，多個 ASP.NET 應用程式也可以藉由指定相同的應用程式名稱，共用設定檔資料來源。

GetPropertyValues 方法

以 SettingsContext 和 SettingsPropertyCollection 物件做為輸入參數。

SettingsContext 會提供使用者資訊。您可以使用資訊做為主索引鍵，以擷取使用者的設定檔屬性資訊。請使用 SettingsContext 物件取得使用者名稱，以及判斷使用者是經過驗證還是匿名。

SettingsPropertyCollection 包含 SettingsProperty 物件的集合。每個 SettingsProperty 物件會提供屬性的名稱和型別，以及像是屬性預設值和屬性是否唯讀的其他資訊。GetPropertyValues 會根據提供做為輸入的 SettingsProperty 物件，使用 SettingsPropertyValue 物件填入 SettingsPropertyValueCollection。將指定使用者之資料來源所提供的值，指派給每個 SettingsPropertyValue 物件的 PropertyValue 屬性，然後傳回整個集合。

呼叫此方法也會將指定使用者設定檔的 LastActivityDate 值，更新為目前的日期和時間。

SetPropertyValues 方法

以 SettingsContext 和 SettingsPropertyValueCollection 物件做為輸入參數。

The SettingsPropertyValueCollection 包含 SettingsPropertyValue 物件的集合。每個 SettingsPropertyValue 物件會提供屬性的名稱、型別和值，以及像是屬性預設值和屬性是否唯讀的其他資訊。SetPropertyValues 方法會更新指定使用者之資料來源中的設定檔屬性值。

呼叫方法也會將指定使用者設定檔的 LastActivityDate 和 LastUpdatedDate 值，更新為目前的日期和時間。

ProfileProvider 成員

成員	說明
DeleteProfiles 方法	以使用者名稱的字串陣列做為輸入參數，並且從資料來源刪除指定名稱的所有設定檔資訊和屬性值，其中應用程式名稱符合 ApplicationName 屬性值。如果資料來源支援交易，建議您將所有的刪除作業包含在一個交易中。如果任何刪除作業失敗，就可以復原交易然後擲回例外狀況。
DeleteProfiles 方法	以 ProfileInfo 物件的集合做為輸入參數，並且從資料來源刪除每個設定檔的所有設定檔資訊和屬性值，其中應用程式名稱符合 ApplicationName 屬性值。如果資料來源支援交易，建議您將所有的刪除作業包含在一個交易中。如果任何刪除作業失敗，就可以復原交易然後擲回例外狀況。
DeleteInactiveProfiles 方法	以 ProfileAuthenticationOption 值和 DateTime 物件做為輸入參數，並於最後一筆活動日期小於或等於指定日期和時間，而且應用程式名稱符合 ApplicationName 屬性值時，從資料來源刪除所有設定檔資訊及屬性值。ProfileAuthenticationOption 參數會指定只傳回匿名設定檔、只刪除已驗證的設定檔，或是刪除的所有設定檔。如果資料來源支援交易，建議您將所有的刪除作業包含在一個交易中。如果任何刪除作業失敗，就可以復原交易然後擲回例外狀況。
GetAllProfiles 方法	以 ProfileAuthenticationOption 值、指定網頁索引的整數、指定網頁大小的整數，以及設為設定檔總數的整數參考做為輸入參數。當應用程式名稱符合 ApplicationName 屬性值時，會傳回 ProfileInfo，其中包含資料來源中所有設定檔的 ProfileInfoCollection 物件。ProfileAuthenticationOption 參數會指定只傳回匿名設定檔、只傳回已驗證的設定檔，或是傳回所有設定檔。 GetAllProfiles 方法所傳回的結果是由頁面索引和頁面大小值加以限制。頁面大小值會指定 ProfileInfoCollection 中所要傳回 ProfileInfo 物件的最大數目。頁面索引值會指定要傳回的結果頁，其中 1 代表第一頁。資料錄總數這個參數是一個 out 參數 (在 Visual Basic 中可以使用 ByRef)，其值會被設定為設定檔的總數。例如，如果資料存放區包含應用程式的 13 個設定檔，而頁面索引值是 6 且頁面大小為 5，則傳回的 ProfileInfoCollection 即包含第六到第十個設定檔。方法傳回時，資料錄總數值是設定為 13。
GetAllInactiveProfiles 方法	以 ProfileAuthenticationOption 值、 DateTime 物件、指定網頁索引的整數、指定網頁大小的整數，以及設為設定檔總數的整數參考做為輸入參數。當應用程式名稱符合 ApplicationName 屬性值，且最後一筆活動日期小於或等於指定的 DateTime 時，會傳回 ProfileInfoCollection，其中包含資料來源中所有設定檔的 ProfileInfo 物件。ProfileAuthenticationOption 參數會指定只傳回匿名設定檔、只傳回已驗證的設定檔，或是傳回所有設定檔。 GetAllInactiveProfiles 方法所傳回的結果是由頁面索引和頁面大小值加以限制。頁面大小值會指定 ProfileInfoCollection 中所要傳回 ProfileInfo 物件的最大數目。頁面索引值會指定要傳回的結果頁，其中 1 代表第一頁。資料錄總數這個參數是一個 out 參數 (在 Visual Basic 中可以使用 ByRef)，其值會被設定為設定檔的總數。例如，如果資料存放區包含應用程式的 13 個設定檔，而頁面索引值是 2 且頁面大小為 5，則傳回的 ProfileInfoCollection 即包含第六到第十個設定檔。方法傳回時，資料錄總數值是設定為 13。
FindProfilesByUserName 方法	以 ProfileAuthenticationOption 值、包含使用者名稱的字串、指定網頁索引的整數、指定網頁大小的整數，以及設為設定檔總數的整數參考做為輸入參數。當使用者名稱符合指定的使用者名稱，且應用程式名稱符合 ApplicationName 屬性值時，會傳回 ProfileInfoCollection，其中包含資料來源中所有設定檔的 ProfileInfo 物件。ProfileAuthenticationOption 參數會指定只傳回匿名設定檔、只傳回已驗證的設定檔，或是傳回所有設定檔。如果資料來源支援像是萬用字元的其他搜尋功能，您可以提供更廣泛的使用者名稱搜尋功能。 FindProfilesByUserName 方法所傳回的結果是由頁面索引和頁面大小值加以限制。頁面大小值會指定 ProfileInfoCollection 中所要傳回 ProfileInfo 物件的最大數目。頁面索引值會指定要傳回的結果頁，其中 1 代表第一頁。資料錄總數這個參數是一個 out 參數 (在 Visual Basic 中可以使用 ByRef)，其值會被設定為設定檔的總數。例如，如果資料存放區包含應用程式的 13 個設定檔，而頁面索引值是 2 且頁面大小為 5，則傳回的 ProfileInfoCollection 即包含第六到第十個設定檔。方法傳回時，資料錄總數值是設定為 13。
FindInactiveProfilesByUserName 方法	以 ProfileAuthenticationOption 值、包含使用者名稱的字串、DateTime 物件、指定網頁索引的整數、指定網頁大小的整數，以及設為設定檔總數的整數參考做為輸入參數。當應用程式名稱符合 ApplicationName 屬性值，且最後一筆活動日期小於或等於指定的 DateTime 時，會傳回 ProfileInfoCollection，其中包含資料來源中所有設定檔的 ProfileInfo 物件。ProfileAuthenticationOption 參數會指定只傳回匿名設定檔、只傳回已驗證的設定檔，或是傳回所有設定檔。如果資料來源支援像是萬用字元的其他搜尋功能，您可以提供更廣泛的使用者名稱搜尋功能。 FindInactiveProfilesByUserName 方法所傳回的結果是由頁面索引和頁面大小值加以限制。頁面大小值會指定 ProfileInfoCollection 中所要傳回 ProfileInfo 物件的最大數目。頁面索引值會指定要傳回的結果頁，其中 1 代表第一頁。資料錄總數這個參數是一個 out 參數 (在 Visual Basic 中可以使用 ByRef)，其值會被設定為設定檔的總數。例如，如果資料存放區包含應用程式的 13 個設定檔，而頁面索引值是 2 且頁面大小為 5，則傳回的 ProfileInfoCollection 即包含第六到第十個設定檔。方法傳回時，資料錄總數值是設定為 13。
GetNumberOfInactiveProfiles 方法	以 ProfileAuthenticationOption 值和 DateTime 物件做為輸入參數，並於最後一筆活動日期小於或等於指定的 DateTime，且應用程式名稱符合 ApplicationName 屬性值時，傳回資料來源中所有設定檔的計數。ProfileAuthenticationOption 參數會指定只傳回匿名設定檔、只計數已驗證的設定檔，或是計數所有的設定檔。

ApplicationName

因為設定檔提供者會分開儲存每個應用程式的設定檔資訊，所以您必須確認資料結構描述、查詢以及更新中務必包含應用程式名稱。例如，下列命令是用來根據使用者名稱和設定檔是否匿名，以便從資料庫擷取屬性值，同時確認查詢中包含 ApplicationName 值。

SELECT Property FROM PropertyTable 
  WHERE Username = 'user1' AND IsAnonymous = False 
  AND ApplicationName = 'MyApplication'

請參閱

工作

HOW TO：建置並執行設定檔提供者範例

概念

ASP.NET 設定檔屬性概觀

ASP.NET 設定檔提供者

共用方式為