自訂伺服器控制項的中繼資料屬性
更新：2007 年 11 月
中繼資料屬性 (Attribute) 會套用至伺服器控制項與其成員，以提供設計工具、ASP.NET Web 網頁剖析器、ASP.NET 執行階段，和 Common Language Runtime 所使用的資訊。當網頁開發人員使用視覺化設計工具中的控制項時，設計階段屬性可增加設計階段時的開發人員經驗。僅限設計階段屬性 (Attribute) 在網頁要求期間，對控制項功能來說沒有作用。當 ASP.NET Web 網頁剖析器讀取網頁中的控制項宣告式語法時，會使用控制項的剖析階段屬性 (Attribute)。剖析階段和執行階段屬性，是在網頁上執行控制項的基本屬性。
本主題說明中繼資料屬性 (Attribute)，您通常會將這些屬性 (Attribute) 套用至控制項及其公用屬性 (Property) 和事件。
套用至控制項的屬性
屬性 |
範例 |
|---|---|
AspNetHostingPermissionAttribute JIT 編譯時期程式碼存取安全屬性 (Security Attribute) 確定連結至控制項的程式碼是否具有適當的安全權限時，需要這個屬性。Control 類別會以兩個 JIT 編譯時期程式碼存取安全屬性標記： AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal) 和 AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal)。 您應該將第一個屬性套用至控制項，但不需要套用第二個屬性，因為繼承 (Inheritance) 要求是可轉移並且在衍生類別中維持為作用中。如需詳細資訊，請參閱 SecurityAction。 |
[AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)] 適用於逐步解說：開發和使用自訂的伺服器控制項中的 WelcomeLabel 範例控制項。 |
|
剖析階段屬性 使自訂控制項產生器 (Custom Control Builder) 和控制項產生關聯。只有當您要使用自訂控制項產生器修改預設邏輯 (網頁剖析器使用此邏輯剖析控制項的宣告式語法) 時，才需要套用這個屬性 (Attribute)。如果您只要指定控制項標記中的內容是否對應於屬性 (Property) 或子控制項，請使用 ParseChildrenAttribute (稍後會在此表中描述)，而不使用自訂控制項產生器。 |
[ControlBuilder(typeof(MyControlBuilder))] |
|
設計階段和執行階段屬性 指定當做控制項預設值使用的屬性。套用這個屬性可讓控制項於執行階段時，在查詢中當做參數使用，並定義在執行階段時 ControlParameter 物件要繫結至的預設值。 |
[ControlValueProperty("Text")] |
|
設計階段屬性 指定視覺化設計工具中，控制項的預設事件。在許多視覺化設計工具中，當網頁開發人員按兩下設計介面上的控制項時，就會開啟程式碼編輯器，其游標會定位在預設事件的事件處理常式中。 |
[DefaultEvent("Submit")] 適用於複合 Web 控制項範例中的 Register 範例控制項。 |
|
設計階段屬性 當網頁開發人員在設計介面上選取控制項時，在這個屬性 (Attribute) 中指定的屬性 (Property) 會在視覺化設計工具的屬性瀏覽器中反白顯示。 |
[DefaultProperty("Text")] 適用於逐步解說：開發和使用自訂的伺服器控制項中的 WelcomeLabel 範例控制項。 |
|
設計階段屬性 指定與控制項相關聯的設計工具類別。控制項設計工具類別，負責視覺化設計工具的設計介面上相關聯之控制項的外觀和行為。 |
[Designer(typeof(SimpleCompositeControlDesigner))] 適用於逐步解說：建立 Web 伺服器控制項的基本控制項設計工具中的範例控制項。 |
|
剖析階段屬性 指定控制項標記中的內容是否對應於屬性或子控制項。Control 類別標記為 ParseChildren(false)，表示網頁剖析器將控制項標記的內容轉譯為子控制項。WebControl 類別標記為 ParseChildren(true)，表示網頁剖析器將控制項標記的內容轉譯為屬性。只有當您要修改在 WebControl 類別上的 ParseChildrenAttribute 屬性中指定的邏輯時，才需要套用這個屬性。 |
[ParseChildren(true, "Contacts")] 適用於 Web 控制項集合屬性範例中的 QuickContacts 範例控制項。 |
|
設計階段屬性 指定在網頁中以宣告方式使用控制項時，視覺化設計工具是否應該保存控制項標記中的子控制項或屬性。Control 類別標記為 PersistChildren(true)，表示設計工具保存控制項標記中的子控制項。WebControl 類別標記為 PersistChildren(false)，表示設計工具將屬性 (Property) 保存為控制項標記中的屬性 (Attribute)。 |
[PersistChildren(false)] 適用於 WebControl 類別，並可用於衍生自這個類別的大多數控制項。但是，容器控制項 (例如在其標記中保存子控制項的 Panel) 會標記為 PersistChildren(true) 和 ParseChildren(false)。 |
|
剖析階段屬性 指定控制項是否可受主題或控制面板影響。如果控制項型別已標記指出無法在其中套用主題，則該控制項的所有成員都不會受主題影響。 |
[Themeable(false)] 套用前述範例中所示的屬性，以預防控制項及其所有成員受主題或控制面板所影響。 |
|
設計階段屬性 指定從工具箱建立控制項時，視覺化設計工具對標籤建立的標記格式。 |
[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"] 適用於逐步解說：開發和使用自訂的伺服器控制項中的 WelcomeLabel 範例控制項。 |
|
設計階段屬性 指定視覺化設計工具是否應該在工具箱顯示控制項或元件。根據預設，控制項永遠會顯示在工具箱中。只需要將這個屬性 (Attribute) 套用至您不希望在工具箱中顯示的控制項 (例如樣板屬性 (Property) 的擁有者)。 |
[ToolboxItem(false)] 適用於樣板化伺服器控制項範例中的 TemplateOwner 控制項。 |
|
設計階段屬性 指定由驗證控制項檢查的屬性名稱。這通常是使用者在執行階段時提供其值的屬性，例如 TextBox 控制項的 Text 屬性。在視覺化設計工具中，允許網頁開發人員選取驗證控制項目標的對話方塊，會在網頁上列出取自控制項，以 ValidationPropertyAttribute 指定的屬性。 |
[ValidationProperty("Text")] |
套用至公用屬性 (Property) 的屬性 (Attribute)
屬性 |
範例 |
|---|---|
|
設計階段屬性 指定這個屬性 (Attribute) 是否對於將資料繫結至屬性 (Property) 有意義。在視覺化設計工具中，屬性瀏覽器可以在對話方塊中顯示控制項的可繫結屬性 (例如，在 Visual Studio 中，可繫結屬性會顯示在 [DataBindings] 對話方塊中)。當屬性 (Property) 沒有以這個屬性 (Attribute) 特別標記時，屬性瀏覽器會將值推斷為 Bindable(false)。 |
[Bindable(true)] 適用於逐步解說：開發和使用自訂的伺服器控制項中 WelcomeLabel 範例控制項的 Text 屬性。 |
|
設計階段屬性 指定屬性是否應該顯示在視覺化設計工具的屬性瀏覽器中。將 Browsable(false) 套用至您不希望在屬性瀏覽器中顯示的屬性。當屬性 (Property) 不是以這個屬性 (Attribute) 標記時，會由屬性瀏覽器推斷為預設值 Browsable(true)。 |
[Browsable(false)] 適用於樣板化伺服器控制項範例中 VacationHome 範例控制項的 Template 屬性。 |
|
設計階段屬性 指定如何在視覺化設計工具的屬性瀏覽器中對屬性進行分類。例如，當網頁開發人員使用屬性瀏覽器的分類檢視時，Category("Appearance") 會通知屬性瀏覽器在 [外觀] 分類中顯示屬性。您可以指定與屬性瀏覽器的現有分類相對應的字串引數，或建立自己的分類。 |
[Category("Appearance")] 適用於逐步解說：開發和使用自訂的伺服器控制項中 WelcomeLabel 範例控制項的 Text 屬性。 |
|
設計階段屬性 指定屬性的預設值。這個值應該與您從屬性存取子 (getter) 傳回的預設值相同。在某些視覺化設計工具中 (例如 Visual Studio)，DefaultValueAttribute 屬性可讓網頁開發人員使用快速鍵功能表上的 [重設] 命令，將屬性值重設為預設值。 |
[DefaultValue("")] 適用於逐步解說：開發和使用自訂的伺服器控制項中 WelcomeLabel 範例控制項的 Text 屬性。 |
|
設計階段屬性 指定屬性的概要說明。在 Visual Studio 這類視覺化設計工具中，屬性瀏覽器通常會在視窗的底部，顯示所選取屬性的說明。 |
[Description("The welcome message text.")] 適用於逐步解說：開發和使用自訂的伺服器控制項中 WelcomeLabel 範例控制項的 Text 屬性。 |
DesignerSerializationVisibilityAttribute 設計階段屬性 指定是否要序列化在設計階段時所設定的屬性，或其內容 (例如子屬性或集合項目)。屬性 (Attribute) 之建構函式的引數是 DesignerSerializationVisibility 列舉型別的值。未套用這個屬性 (Attribute) 且已序列化屬性 (Property) 值時，將使用預設值 Visible。 |
[DesignerSerializationVisibility (DesignerSerializationVisibility.Content)] 適用於伺服器控制項屬性範例中 Book 範例控制項的 Author 屬性。 |
|
設計階段屬性 使自訂 UITypeEditor 編輯器與屬性 (Property) 或屬性型別產生關聯。如果這個屬性 (Attribute) 已套用至型別，則不需要套用至該型別的屬性 (Property)。 |
[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))] 適用於 Web 控制項集合屬性範例中 QuickContacts 範例控制項的 Contacts 屬性。 |
|
設計階段屬性 指定屬性 (Property) 名稱是否出現在原始碼編輯器的 IntelliSense 清單中。這個屬性也可以套用至方法和事件。屬性 (Attribute) 之建構函式的引數是 EditorBrowsableState 列舉型別的值。未套用這個屬性時，會使用預設值 Always。 |
[EditorBrowsableAttribute (EditorBrowsableState.Never)] 套用前一個範例中顯示的屬性，以便在 IntelliSense 中隱藏成員。 |
|
設計階段和剖析階段屬性 指定屬性是否可以參與裝置和瀏覽器篩選。篩選可讓網頁開發人員在單一控制項宣告中，對不同的瀏覽器指定不同的屬性值。例如，網頁開發人員可以使用篩選對 Label 控制項的 Text 屬性設定不同的值，如下列語法所示： "UP" 和 "IE" 是瀏覽器篩選條件。未套用這個屬性時，會使用預設值 Filterable(true)。 |
[Filterable(false)] 套用前一個範例中顯示的屬性 (Attribute)，以便從裝置和瀏覽器篩選中排除屬性 (Property)。 |
|
設計階段屬性 指定這個屬性 (Attribute) 對當地語系化屬性 (Property) 是否有意義。屬性 (Property) 標記為 Localizable(true) 時，會在資源檔中儲存屬性值。未套用這個屬性時，會使用預設值 Localizable(false)。 |
[Localizable(true)] 適用於逐步解說：開發和使用自訂的伺服器控制項中 WelcomeLabel 範例控制項的 Text 屬性。 |
|
設計階段屬性 指定在屬性瀏覽器中，對子屬性所做的變更是否應該傳送至父屬性。 |
[NotifyParentProperty(true)] 適用於伺服器控制項屬性範例中定義之 Author 型別的 FirstName、LastName 和 MiddleName 屬性。 |
|
設計階段屬性 指定是否將屬性 (Property) 保存為控制項標籤上的屬性 (Attribute)，或保存為控制項標籤中的巢狀內容。屬性 (Attribute) 之建構函式的引數是 PersistenceMode 列舉型別的值。 |
[PersistenceMode(PersistenceMode.InnerProperty)] 適用於伺服器控制項屬性範例中 Book 範例控制項的 Author 屬性。 |
|
設計階段和剖析階段屬性 指定屬性的命名容器型別，它會傳回 ITemplate 介面。 |
[TemplateContainer(typeof(CustomTemplateContainer))] 套用前述範例中所示的屬性，以指定由 CustomTemplateContainer 類別表示的 ITemplate 屬性。 |
|
設計階段和剖析階段屬性 指定樣板屬性是否允許建立單一或多重執行個體。如果樣板屬性並未使用 TemplateInstanceAttribute 屬性擴充，則預設會建立多重執行個體。 |
[TemplateInstance(TemplateInstance.Single)] 套用前述範例中所示的屬性，以指定只能建立樣板屬性的一個執行個體。 |
|
剖析階段屬性 指定控制項成員是否可受主題或控制面板影響。依照預設，如果控制項型別本身可以套用主題的話，則由控制項公開的所有屬性都可以套用主題。 |
[Themeable(false)] 套用前述範例中所示的屬性，以預防控制項成員受主題或控制面板所影響。 |
|
設計階段、剖析階段和執行階段屬性 使型別轉換子 (Type Converter) 與屬性或屬性型別產生關聯。型別轉換子會執行從字串表示到指定型別的轉換，反之亦然。 |
[TypeConverter(typeof(AuthorConverter))] 適用於伺服器控制項屬性範例中定義的 Author 型別。 |
|
設計階段和執行階段屬性 指定字串屬性表示 URL 值，可讓您使 URL 產生器和屬性產生關聯。 |
[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)] 套用以設定 ASP.NET 檔案的特定檔案篩選條件，並可允許絕對和相對路徑。 |
套用至事件成員的屬性
套用至事件成員的主要屬性為三個設計階段屬性：BrowsableAttribute、CategoryAttribute，和 DescriptionAttribute。這些屬性 (Attribute) 也可以套用至屬性 (Property)，並已經在之前的表格中說明。如需程式碼範例，請查看複合 Web 控制項範例中 Register 範例控制項的 Submit 事件。