Поделиться через

Атрибуты метаданных для специализированных серверных элементов управления

  • Статья

Обновлен: Ноябрь 2007

Атрибуты метаданных применяются к серверным элементам управления и их членам для предоставления сведений, используемых средствами разработки, анализатором страниц ASP.NET, средой разработки ASP.NET и общеязыковой средой выполнения (CLR). Атрибуты времени разработки расширяют возможности разработчика во время разработки, когда разработчик страниц использует элемент управления в визуальном конструкторе. Атрибуты только времени разработки не оказывают влияния на функциональные возможности элемента управления при запросе страницы. Атрибуты времени анализа элемента управления используются анализатором страниц ASP.NET при считывании декларативного синтаксиса элемента управления на странице. Атрибуты времени разработки и времени выполнения необходимы для функционирования элемента управления на странице.

В этом разделе описываются атрибуты метаданных, которые широко применяются к элементам управления и их общедоступным свойствам и событиям.

Атрибуты, применяемые к элементу управления

Атрибут

Пример

AspNetHostingPermissionAttribute

Атрибут управления доступа для кода времени компиляции JIT.

Необходим, чтобы удостовериться, что код, который связан с элементом управления, обладает необходимыми разрешениями безопасности. Класс Control помечен двумя атрибутами управления доступа для кода времени компиляции JIT:

AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)

и AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal).

Необходимо применить первый атрибут к элементу управления, однако нет необходимости применять второй атрибут, так как требование наследования является транзитивным и остается в силе для производных классов. Дополнительные сведения см. в разделе SecurityAction.

[AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)]

Применяется к примеру элемента управления WelcomeLabel в Пошаговое руководство. Создание и использование пользовательского серверного элемента управления.

ControlBuilderAttribute

Атрибут времени анализа.

Связывает построитель пользовательских элементов управления с элементом управления. Необходимо применять этот атрибут, только если необходимо использовать построитель пользовательских элементов управления для изменения логики по умолчанию, используемой анализатором страниц для анализа декларативного синтаксиса элемента управления. Если необходимо указать только соответствие содержимого тегов элемента управления свойствам или дочерним элементам управления, используйте ParseChildrenAttribute (описывается далее в этой таблице) вместо построителя пользовательских элементов.

[ControlBuilder(typeof(MyControlBuilder))]

ControlValuePropertyAttribute

Атрибут времени разработки и времени выполнения.

Указывает свойство, которое используется в качестве значения по умолчанию для элемента управления. Применение этого атрибута позволяет использовать элемент управления в качестве параметра в очереди во время выполнения и задает значение по умолчанию, к которому осуществляется привязка объекта ControlParameter во время выполнения.

[ControlValueProperty("Text")]

DefaultEventAttribute

Атрибут времени разработки.

Задает событие по умолчанию для элемента управления в визуальном конструкторе. Во многих визуальных конструкторах, когда разработчик страниц дважды щелкает элемент управления на поверхности разработки, открывается редактор кода с курсором, установленным в обработчике событий для события по умолчанию.

[DefaultEvent("Submit")]

Применяется к примеру элемента управления Register в Пример составного веб-элемента управления.

DefaultPropertyAttribute

Атрибут времени разработки.

Свойство, указанное в этом атрибуте, выделяется в обозревателе свойств визуального конструктора, когда разработчик страниц выбирает элемент управления на поверхности разработки.

[DefaultProperty("Text")]

Применяется к примеру элемента управления WelcomeLabel в Пошаговое руководство. Создание и использование пользовательского серверного элемента управления.

DesignerAttribute

Атрибут времени разработки.

Задает класс разработчика, связанный с элементом управления. Класс разработчика элемента управления отвечает за внешний вид и поведения связанного элемента управления на поверхности разработки визуального конструктора.

[Designer(typeof(SimpleCompositeControlDesigner))]

Применяется к примерам элементов управления Пошаговое руководство. Создание базового конструктора элементов управления для серверного веб-элемента управления

ParseChildrenAttribute

Атрибут времени анализа.

Указывает, относится ли содержимое в теге элемента управления к свойствам или дочерним элементам управления. Класс Control отмечен ParseChildren(false), что означает, что анализатор страницы интерпретирует содержимое в тегах элемента управления как дочерние элементы управления. Класс WebControl отмечен ParseChildren(true), что означает, что анализатор страниц интерпретирует содержимое в тегах элемента управления как свойства. Этот атрибут следует применять, только если необходимо изменить логику, указанную в атрибуте ParseChildrenAttribute класса WebControl.

[ParseChildren(true, "Contacts")]

Применяется к примеру элемента управления QuickContacts в Пример свойства-коллекции веб-элементов.

PersistChildrenAttribute

Атрибут времени разработки.

Указывает, должен ли визуальный конструктор сохранять дочерние элементы управления или свойства в теге элемента управления при декларативном использовании элемента управления на странице. Класс Control помечен PersistChildren(true), что означает, что конструктор сохраняет дочерние элементы управления в тегах элемента управления. Класс WebControl помечен PersistChildren(false), что означает, что конструктор сохраняет свойства как атрибуты в тегах элемента управления.

[PersistChildren(false)]

Применяется к классу WebControl и подходит для большинства элементов управления, которые наследуют от классов. Однако контейнерные элементы управления, например Panel, которые сохраняют дочерние элементы управления в тегах, помечены PersistChildren(true) и ParseChildren(false).

ThemeableAttribute

Атрибут времени анализа.

Указывает, могут ли на элемент управления оказывать влияние темы или обложки элементов управления. Если тип элемента управления помечен таким образом, чтобы темы не могли применяться к нему, все другие члены элемента управления также не подвергаются влиянию тем.

[Themeable(false)]

Примените атрибут, показанный в предыдущем примере, для предотвращения влияния тем и обложек элементов управления на элемент управления и его члены.

ToolboxDataAttribute

Атрибут времени разработки.

Задает формат разметки, созданной для тега визуальным конструктором, когда элемент управления создается с панели элементов.

[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"]

Применяется к примеру элемента управления WelcomeLabel в Пошаговое руководство. Создание и использование пользовательского серверного элемента управления.

ToolboxItemAttribute

Атрибут времени разработки.

Указывает, должен ли визуальный конструктор отображать элемент управления или компонент в панели элементов. По умолчанию элементы управления всегда отображаются в панели элементов. Этот атрибут необходимо применять только к элементу управления (например владельце свойства шаблона), который не должен отображаться в панели элементов.

[ToolboxItem(false)]

Применяется к элементу управления TemplateOwner в Пример шаблонного серверного элемента управления.

ValidationPropertyAttribute

Атрибут времени разработки.

Указывает имя свойства, которое проверяется с помощью проверяющего элемента управления. Обычно это свойство, значение которого определяется пользователями во время выполнения, например свойство Text элемента управления TextBox. В визуальном конструкторе диалоговое окно, которое позволяет разработчикам страниц выбирать цель проверяющих элементов управления, содержит список свойств, указанных с помощью ValidationPropertyAttribute из элементов управления на странице.

[ValidationProperty("Text")]

Атрибуты, применяемые к общим свойствам

Атрибут

Пример

BindableAttribute

Атрибут времени разработки.

Указывает, является ли целесообразной привязка данных к свойству. В визуальном конструкторе обозреватель свойство может отображать свойства связывания элемента управления в диалоговом окне. Например, в Visual Studio, свойства связывания отображаются в диалоговом окне Привязка данных. Если свойство не отмечено этим атрибутом, то обозреватель свойств присваивает ему значение Bindable(false).

[Bindable(true)]

Применяется к свойству Text примера элемента управления WelcomeLabel в Пошаговое руководство. Создание и использование пользовательского серверного элемента управления.

BrowsableAttribute

Атрибут времени разработки.

Указывает, следует ли отображать свойство в обозревателе свойств визуального конструктора. Примените Browsable(false) к свойству, которое не должно отображаться в обозревателе свойств. Свойство по умолчанию Browsable(true) выводится обозревателем свойств, если свойство не отмечено этим атрибутом.

[Browsable(false)]

Применяется к свойству Template в примере элемента управления VacationHome в Пример шаблонного серверного элемента управления.

CategoryAttribute

Атрибут времени разработки.

Указывает, как классифицировать свойства в обозревателе свойств визуального конструктора элементов. Например, Category("Appearance") означает, что обозреватель свойств должен отображать свойство в категории «Внешний вид», когда разработчик страниц использует представление категорий в обозревателе свойств. Можно указать строковой аргумент, соответствующий существующей категории в обозревателе свойств, или можно создать собственную категорию.

[Category("Appearance")]

Применяется к свойству Text примера элемента управления WelcomeLabel в Пошаговое руководство. Создание и использование пользовательского серверного элемента управления.

DefaultValueAttribute

Атрибут времени разработки.

Задает для свойства значение по умолчанию. Это значение должно быть равно значению, возвращаемому методом получения доступа к свойству. В некоторых визуальных конструкторах, например Visual Studio, атрибут DefaultValueAttribute позволяет разработчику страниц восстанавливать значение по умолчанию для свойства с помощью команды Сброс контекстного меню.

[DefaultValue("")]

Применяется к свойству Text примера элемента управления WelcomeLabel в Пошаговое руководство. Создание и использование пользовательского серверного элемента управления.

DescriptionAttribute

Атрибут времени разработки.

Задает краткое описание свойства. В визуальном конструкторе, таком как Visual Studio, обозреватель свойств задает описание выбранного свойства, как правило, в нижней части окна.

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

Применяется к свойству Text примера элемента управления WelcomeLabel в Пошаговое руководство. Создание и использование пользовательского серверного элемента управления.

DesignerSerializationVisibilityAttribute

Атрибут времени разработки.

Указывает, необходима ли сериализация свойства или содержимого (например вложенных свойств или элементов коллекции), установленных во время разработки. Аргументом конструктора атрибута является значение перечисления DesignerSerializationVisibility. Значение по умолчанию Visible выводится, если этот атрибут не применяется. При этом выполняется сериализация значения свойства.

[DesignerSerializationVisibility

(DesignerSerializationVisibility.Content)]

Применяется к свойству Author примера элемента управленияBook в Пример использования свойств серверного веб-элемента управления.

EditorAttribute

Атрибут времени разработки.

Связывает пользовательский редактор UITypeEditor со свойством или типом свойства. Если атрибут применяется к типу, не требуется применять его к свойству этого типа.

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

Применяется к свойству Contacts примера элемента управленияQuickContacts в Пример свойства-коллекции веб-элементов.

EditorBrowsableAttribute

Атрибут времени разработки.

Указывает, отображается ли имя свойства в списке IntelliSense редактора исходного кода. Данный атрибут можно также применять для методов и событий. Аргументом конструктора атрибута является значение перечисления EditorBrowsableState. Значение по умолчанию Always выводится, если не применяется атрибут.

[EditorBrowsableAttribute

(EditorBrowsableState.Never)]

Примените атрибут, показанный в предыдущем примере, для скрытия члена в IntelliSense.

FilterableAttribute

Атрибут времени разработки и времени анализа.

Указывает, может ли свойство участвовать в фильтрации устройства и обозревателя. Фильтрация позволяет разработчику страниц задавать различные значения свойств для разных обозревателей в одном объявлении элемента управления. Например, разработчик событий может использовать фильтрацию для установки различных значений для свойства Text элемента управления Label, как показано в следующем синтаксисе:

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

«UP» и «IE» являются фильтрами обозревателя. Значение по умолчанию Filterable(true) выводится, если не применяется атрибут.

[Filterable(false)]

Примените атрибут, показанный в предыдущем примере, чтобы исключить свойство из фильтрации устройства и обозревателя.

LocalizableAttribute

Атрибут времени разработки.

Указывает, является ли целесообразной локализация свойства. Если свойство помечено Localizable(true) значение свойства сохраняется в файле ресурсов. Значение по умолчанию Localizable(false) выводится, если не применяется атрибут.

[Localizable(true)]

Применяется к свойству Text примера элемента управления WelcomeLabel в Пошаговое руководство. Создание и использование пользовательского серверного элемента управления.

NotifyParentPropertyAttribute

Атрибут времени разработки.

Указывает, что в обозревателе свойств изменения, внесенные во вложенное свойство, должны отражаться в родительском свойстве.

[NotifyParentProperty(true)]

Применяется к свойствам FirstName, LastName и MiddleName типа Author, определенного в Пример использования свойств серверного веб-элемента управления.

PersistenceModeAttribute

Атрибут времени разработки.

Указывает, сохраняется ли свойство в качестве атрибута в теге элемента управления или в качестве вложенного содержимого в тегах элемента управления. Аргументом конструктора атрибута является значение перечисления PersistenceMode.

[PersistenceMode(PersistenceMode.InnerProperty)]

Применяется к свойству Author примера элемента управления Book в Пример использования свойств серверного веб-элемента управления.

TemplateContainerAttribute

Атрибут времени разработки и времени анализа.

Определяет тип контейнера именования для свойства, которое возвращает интерфейс ITemplate.

[TemplateContainer(typeof(CustomTemplateContainer))]

Примените атрибут, показанный в предыдущем примере, чтобы указать, что свойство ITemplate представляется классом CustomTemplateContainer.

TemplateInstanceAttribute

Атрибут времени разработки и времени анализа.

Указывает, допускает ли свойство шаблона создание одного или нескольких экземпляров. Если свойство шаблона не расширяется атрибутом TemplateInstanceAttribute, по умолчанию разрешается создание нескольких экземпляров.

[TemplateInstance(TemplateInstance.Single)]

Примените атрибут, представленный в предыдущем примере, чтобы указать возможность создания только одного экземпляра свойства шаблона.

ThemeableAttribute

Атрибут времени анализа.

Указывает, могут ли на член элемент управления оказывать влияние темы или обложки элементов управления. По умолчанию ко всем свойствам, представленным элементом управления, применяются темы, если темы применяются к самому типу элемента управления.

[Themeable(false)]

Примените атрибут, показанный в предыдущем примере, для предотвращения влияния тем и обложек элементов управления на член элемента управления.

TypeConverterAttribute

Атрибут времени разработки, времени анализа и времени выполнения.

Связывает преобразователь типов со свойством или типом свойств. Преобразователи типов выполняют преобразование строкового представления в указанный тип и наоборот.

[TypeConverter(typeof(AuthorConverter))]

Применяется к типу Author, определенному в Пример использования свойств серверного веб-элемента управления.

UrlPropertyAttribute

Атрибут времени разработки и времени выполнения.

Указывает, что строковое свойство представляет значение URL, которое позволяет связать средство построения URL со свойством.

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

Примените для установки фильтра определенных файлов для файлов ASP.NET и разрешить абсолютные и относительные пути.

Атрибуты, применяемые к членам-событиям

Основные атрибуты, применяемые к членам-событиям — это три атрибута времени разработки: BrowsableAttribute, CategoryAttribute и DescriptionAttribute. Эти атрибуты также применяются к свойствам и описаны в предыдущей таблице. Пример кода см. в событии Submit примера элемента управления Register в Пример составного веб-элемента управления.

См. также

Задачи

Пошаговое руководство. Создание и использование пользовательского серверного элемента управления

Другие ресурсы

Разработка пользовательских серверных элементов управления ASP.NET