自定义控件属性的特性大全

元数据属性应用于服务器控件及其成员，从而提供由设计工具、ASP.NET 页分析器、ASP.NET 运行库以及公共语言运行库使用的信息。当页开发人员在可视化设计器中使用控件时，设计时属性能改进开发人员的设计时体验。仅用于设计时的属性在页请求期间对控件的功能没有任何影响。控件的分析时属性由 ASP.NET 页分析器在其读取页中控件的声明性语法时使用。分析时属性和运行时属性是保证控件在页中正常工作必不可少的内容。

本主题描述常用于控件及其公共属性 (Property) 和事件的元数据属性 (Attribute)。

应用于控件的属性

 

属性	示例
AspNetHostingPermissionAttribute JIT 编译时代码访问安全属性。 需要使用此属性确保链接到控件的代码具有适当的安全权限。Control 类带有两个 JIT 编译时代码访问安全属性标记： AspNetHostingPermission(SecurityAction.LinkDemand, Level=AspNetHostingPermissionLevel.Minimal) 和 AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal)。 应将第一个属性应用于控件，但并非必须应用第二个属性，因为继承请求是可传递的，在派生类中仍有效。有关更多信息，请参见 SecurityAction。	[AspNetHostingPermission(SecurityAction.LinkDemand, Level=AspNetHostingPermissionLevel.Minimal)] 应用于演练：开发和使用自定义服务器控件中的 WelcomeLabel 示例控件。
ControlBuilderAttribute 分析时属性。 将自定义控件生成器与控件关联。只有在您希望使用自定义控件生成器，对页分析器用于分析控件的声明性语法的默认逻辑进行修改时，才需要应用此属性。如果仅希望指定控件标记中的内容是否与属性或子控件对应，请使用 ParseChildrenAttribute（在此表后面的内容中描述），而不要使用自定义控件生成器。	[ControlBuilder(typeof(MyControlBuilder))]
ControlValuePropertyAttribute 设计时和运行时属性。 指定用作控件的默认值的属性。应用此属性可让一个控件在运行时用作查询中的参数，并可定义 ControlParameter 对象在运行时绑定到的默认值。	[ControlValueProperty("Text")]
DefaultEventAttribute 设计时属性。 在可视化设计器中指定控件的默认事件。在许多可视化设计器中，页开发人员在设计图面上双击控件时，将打开代码编辑器，同时将光标定位到默认事件的事件处理程序中。	[DefaultEvent("Submit")] 应用于复合 Web 控件示例中的 Register 示例控件。
DefaultPropertyAttribute 设计时属性。 当页开发人员在设计图面上选择控件时，此属性 (Attribute) 中指定的属性 (Property) 将在可视化设计器的属性 (Property) 浏览器中突出显示。	[DefaultProperty("Text")] 应用于演练：开发和使用自定义服务器控件中的 WelcomeLabel 示例控件。
DesignerAttribute 设计时属性。 指定与控件关联的设计器类。控件设计器类控制关联的控件在可视化设计器的设计图面上的外观和行为。	[Designer(typeof(SimpleCompositeControlDesigner))] 应用于演练：为 Web 服务器控件创建基本控件设计器中的示例控件。
ParseChildrenAttribute 分析时属性。 指定控件标记中的内容是否与属性或子控件对应。Control 类被标记为 ParseChildren(false)，表示页分析器将控件标记中的内容解释为子控件。WebControl 类被标记为 ParseChildren(true)，表示页分析器将控件标记中的内容解释为属性。只有在您希望对在 WebControl 类的 ParseChildrenAttribute 属性中指定的逻辑进行修改时才需要应用此属性。	[ParseChildren(true, "Contacts")] 应用于 Web 控件集合属性示例中的 QuickContacts 示例控件。
PersistChildrenAttribute 设计时属性。 指定当以声明方式在页中使用控件时，可视化设计器是否应在该控件的标记中保存子控件或属性。Control 类被标记为 PersistChildren(true)，表示设计器在控件标记中保存子控件。WebControl 类被标记为 PersistChildren(false)，表示设计器在控件标记中将属性 (Property) 保存为属性 (Attribute)。	[PersistChildren(false)] 应用于 WebControl 类，并且适用于从此类派生的大多数控件。但是，在其标记中保存子控件的容器控件（如 Panel）被标记为 PersistChildren(true) 和 ParseChildren(false)。
ToolboxDataAttribute 设计时属性。 指定从工具箱创建控件时可视化设计器为标记创建的标记格式。	[ToolboxData("<{0}:WelcomeLabel runat=""server""> </{0}:WelcomeLabel>"] 应用于演练：开发和使用自定义服务器控件中的 WelcomeLabel 示例控件。
ToolboxItemAttribute 设计时属性。 指定可视化设计器应在工具箱中显示控件还是组件。默认情况下，始终在工具箱中显示控件。此属性只能应用于不希望在工具箱中显示的控件（如模板属性的所有者）。	[ToolboxItem(false)] 应用于模板化服务器控件示例中的 TemplateOwner 控件。
ValidationPropertyAttribute 设计时属性。 指定由验证控件检查的属性的名称。通常这些属性的值由用户在运行时提供，如 TextBox 控件的 Text 属性。在可视化设计器中，允许页开发人员选择验证控件目标的对话框会列出通过页上控件中的 ValidationPropertyAttribute 指定的各个属性。	[ValidationProperty("Text")]

 

应用于公共属性 (Property) 的属性 (Attribute)

 

属性

示例

BindableAttribute

设计时属性。

指定将数据绑定到属性是否有意义。在可视化设计器中，属性浏览器可以在对话框中显示控件的可绑定属性。（例如，在 Visual Studio 中，可绑定属性显示在“数据绑定”对话框中。）如果属性 (Property) 没有使用此属性 (Attribute) 标记，则属性 (Property) 浏览器会推断其值为 Bindable(false)。

[Bindable(true)]

应用于演练：开发和使用自定义服务器控件中的 WelcomeLabel 示例控件的 Text 属性。

BrowsableAttribute

设计时属性。

指定是否应在可视化设计器的属性浏览器中显示某个属性。将 Browsable(false) 应用于不希望在属性浏览器中显示的属性。没有通过此属性 (Attribute) 标记某个属性 (Property) 时，属性浏览器会推断其默认值为 Browsable(true)。

[Browsable(false)]

应用于模板化服务器控件示例中的 VacationHome 示例控件中的 Template 属性。

CategoryAttribute

设计时属性。

指定如何在可视化设计器的属性浏览器中对属性进行分类。例如，当页开发人员在属性浏览器中使用分类视图时，Category("Appearance") 将告知属性浏览器在“外观”类别中显示属性。可以指定一个对应于属性浏览器中的现有类别的字符串参数，也可以创建自己的类别。

[Category("Appearance")]

应用于演练：开发和使用自定义服务器控件中的 WelcomeLabel 示例控件的 Text 属性

DefaultValueAttribute

设计时属性。

指定属性的默认值。此值应与从属性访问器 (getter) 返回的默认值相同。在有些可视化设计器（如 Visual Studio）中，DefaultValueAttribute 属性允许页开发人员使用快捷菜单上的“重置”命令将属性值重置为其默认值。

[DefaultValue("")]

应用于演练：开发和使用自定义服务器控件中的 WelcomeLabel 示例控件的 Text 属性

DescriptionAttribute

设计时属性。

指定属性的简短描述。在可视化设计器（如 Visual Studio）中，属性浏览器通常在窗口底部显示选定的属性的描述。

[Description("The welcome message text.")]

应用于演练：开发和使用自定义服务器控件中的 WelcomeLabel 示例控件的 Text 属性

DesignerSerializationVisibilityAttribute

设计时属性。

指定是否对设计时设置的属性或其内容（如子属性或集合项）进行序列化。该属性的构造函数的参数是一个 DesignerSerializationVisibility 枚举值。未应用此属性 (Attribute) 且属性 (Property) 的值已序列化时，则暗示使用默认值 Visible。

[DesignerSerializationVisibility

(DesignerSerializationVisibility.Content)]

应用于服务器控件属性示例中的 Book 示例控件的 Author 属性。

EditorAttribute

设计时属性。

将自定义 UITypeEditor 编辑器与某个属性或属性类型关联。如果已将此属性 (Attribute) 应用于该类型，则不必将其应用于该类型的属性 (Property)。

[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))]

应用于 Web 控件集合属性示例中的 QuickContacts 示例控件的 Contacts 属性。

EditorBrowsableAttribute

设计时属性。

指定属性名称是否显示在源编辑器的 IntelliSense 列表中。也可将此属性应用于方法和事件。此属性的构造函数的参数是一个 EditorBrowsableState 枚举值。未应用此属性时，则暗示使用默认值 Always。

[EditorBrowsableAttribute

(EditorBrowsableState.Never)]

应用前面示例中演示的属性，以隐藏 IntelliSense 中的成员。

FilterableAttribute

设计时和分析时属性。

指定某个属性是否能参与设备和浏览器筛选。页开发人员利用筛选能在一个控件声明中为不同的浏览器指定不同的属性值。例如，页开发人员可以使用筛选为 Label 控件的 Text 属性设置不同的值，其语法如下所示：

	复制代码
<asp:Label UP:Text="Hello" and IE:Text="Welcome to my site" runat="server" />

“UP”和“IE”是浏览器筛选器。未应用此属性时，则暗示使用默认值 Filterable(true)。

[Filterable(false)]

应用前面示例中演示的属性 (Attribute) 以从设备和浏览器筛选中排除某个属性 (Property)。

LocalizableAttribute

设计时属性。

指定对属性进行本地化是否有意义。如果一个属性标记为 Localizable(true)，则对应的属性值存储在资源文件中。未应用此属性时，则暗示使用默认值 Localizable(false)。

[Localizable(true)]

应用于演练：开发和使用自定义服务器控件中的 WelcomeLabel 示例控件的 Text 属性。

NotifyParentPropertyAttribute

设计时属性。

指定在属性浏览器中对子属性所做的更改应传播到父属性。

[NotifyParentProperty(true)]

应用于服务器控件属性示例中定义的 Author 类型的 FirstName、LastName 和 MiddleName 属性。

PersistenceModeAttribute

设计时属性。

指定是将属性 (Property) 保存为控件标记上的属性 (Attribute)，还是将其保存为控件标记中的嵌套内容。此属性的构造函数的参数是一个 PersistenceMode 枚举值。

[PersistenceMode(PersistenceMode.InnerProperty)]

应用于服务器控件属性示例中的 Book 示例控件的 Author 属性。

TypeConverterAttribute

设计时、分析时和运行时属性。

将类型转换器与某个属性或属性类型关联。类型转换器执行从字符串表示形式到指定类型（或相反）的转换。

[TypeConverter(typeof(AuthorConverter))]

应用于服务器控件属性示例中定义的 Author 类型。

UrlPropertyAttribute

设计时和运行时属性。

指定一个字符串属性表示一个 URL 值，利用此值可以将 URL 生成器与该属性关联起来。

[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)]

应用于为 ASP.NET 文件设置特定的文件筛选器，并且允许绝对路径和相对路径。

 

应用于事件成员的属性

应用于事件成员的主属性包括三个设计时属性：BrowsableAttribute、CategoryAttribute 和 DescriptionAttribute。这些属性 (Attribute) 还应用于属性 (Property)，前面的表已对这些属性 (Attribute) 进行了描述。有关代码示例，请参见复合 Web 控件示例中的 Register