Atributos Metadata para Controles de Servidor Personalizados
Atributos de metadados são aplicados aos controles de servidor e aos seus membros para fornecer informações que são usadas por ferramentas de design, o analisador de páginas ASP.NET, o tempo de execução do ASP.NET e o Tempo de Execução Common Language.Atributos de tempo de design melhoram a experiência do desenvolvedor no tempo de design quando um desenvolvedor de página usa o controle em um designer visual.Atributos somente em tempo de design não têm nenhum efeito sobre a funcionalidade de um controle durante uma solicitação de página.Atributos em tempo de análise de um controle são usados pelo analisador de página ASP.NET quando ele lê a sintaxe declarativa do controle em uma página.Atributos em tempo de análise e em tempo de execução são essenciais para o funcionamento de um controle em uma página.
Este tópico descreve os atributos de metadados que você aplicará comumente para controles e suas propriedades públicas e eventos.
Atributos Aplicados a um controle
Atributo |
Exemplo |
|---|---|
AspNetHostingPermissionAttribute Atributo de segurança de acesso a código JIT em tempo de compilação. Necessário para garantir que o código que referencia o controle tem as permissões de segurança apropriadas.A classe Control é marcada com dois atributos JIT de segurança de acesso a código em tempo de compilação: AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal) e AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal). Você deve aplicar o primeiro atributo para o controle, mas você não têm que aplicar o segundo porque uma demanda de herança é transitiva e permanece em vigor em classes derivadas.Para obter mais informações, consulte SecurityAction. |
[AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)] Aplicado ao controle exemplo WelcomeLabel em Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado. |
|
Atributo em Tempo de Análise. Associa um construtor de controle personalizado ao controle.Você precisará aplicar este atributo somente se você desejar usar um construtor de controle personalizado para modificar a lógica padrão que o analisador de página usa para análise da sintaxe declarativa do controle.Se você apenas quiser especificar se o conteúdo dentro de marcas de controle corresponde aos controles propriedades ou filho, uso ParseChildrenAttribute (descrito posteriormente nesta tabela) em vez de um construtor controle personalizado. |
[ControlBuilder(typeof(MyControlBuilder))] |
|
Atributo em tempo de design e em tempo de execução. Especifica a propriedade que é usada como o valor padrão para um controle.Aplicar este atributo permite um controle a ser usado como um parâmetro em uma consulta em tempo de execução e define o valor padrão que um objeto ControlParameter vincula em tempo de execução. |
[ControlValueProperty("Text")] |
|
Atributo em Tempo de Design. Especifica o evento padrão para o controle em um criador visual.Em muitos designers visuais, quando o desenvolvedor de página clica duas vezes no controle na superfície de design, o editor de códigos é aberto com o cursor posicionado no manipulador de eventos para o evento padrão. |
[DefaultEvent("Submit")] Aplicado ao controle exemplo Register em Exemplo de Controle Web de Composição. |
|
Atributo em Tempo de Design. A propriedade especificada nesse atributo é realçada no pesquisador de propriedades de um criador visual quando o desenvolvedor da página seleciona o controle na superfície de design. |
[DefaultProperty("Text")] Aplicado ao controle exemplo WelcomeLabel em Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado. |
|
Atributo em Tempo de Design. Especifica a classe do designer que está associada com um controle.Uma classe do designer de controle é responsável pela aparência e comportamento do controle associado em um designer do visual da superfície de design. |
[Designer(typeof(SimpleCompositeControlDesigner))] Aplicado ao controle exemplo em Demonstra Passo a passo: Criando um criador controle básico para um controle de servidor Web . |
|
Atributo em Tempo de Análise. Especifica se o conteúdo dentro de uma marca de controle corresponde a propriedades ou controles filho.A classe Control está marcada como ParseChildren(false), o que significa que o analisador de página interpreta o conteúdo dentro das marcas do controle como controles filho.A classe WebControl está marcada como ParseChildren(true), o que significa que o analisador de página interpreta o conteúdo dentro de marcas do controle como propriedades.Você precisará aplicar somente se você desejar modificar a lógica especificada no atributo ParseChildrenAttribute na classe WebControl. |
[ParseChildren(true, "Contacts")] Aplicado ao controle exemplo QuickContacts em Exemplo da propriedade de coleção do controle da Web. |
|
Atributo em Tempo de Design. Especifica se um criador visual deve persistir com controles filho ou propriedades dentro de uma marca de controle quando o controle é usado declarativamente em uma página.A classe Control está marcada como PersistChildren(true), o que significa que o designer persiste com controles filho dentro das marcas do controle.A classe WebControl está marcada como PersistChildren(false), o que significa que o designer persiste com propriedades como atributos dentro das marcas do controle. |
[PersistChildren(false)] Aplicado à classe WebControl e apropriado para a maioria dos controles que derivam dessa classe.No entanto, recipientes de controles, como Panel que persistirem com controles filho dentro de suas marcas são marcados PersistChildren(true) e ParseChildren(false). |
|
Atributo em Tempo de Análise. Especifica se um controle pode ser afetado por temas ou capas de controle.Se um tipo de controle está marcado para indicar que os temas não podem ser aplicados a ele, em seguida, todos os membros do controle da mesma forma não são afetados por temas. |
[Themeable(false)] Aplique o atributo mostrado no exemplo anterior para impedir que um controle e todos os seus membros sejam afetados por temas ou capas de controle. |
|
Atributo em Tempo de Design. Especifica o formato da marcação criada para a marca pelo designer visual quando o controle é criado na caixa de ferramentas. |
[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"] Aplicado ao controle exemplo WelcomeLabel em Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado. |
|
Atributo em Tempo de Design. Especifica se um criador visual deve exibir um controle ou um componente na caixa de ferramentas.Por padrão, os controles são sempre exibidos na caixa de ferramentas.Você precisará aplicar isto somente a um controle (tal como o proprietário de uma propriedade de modelo) que você não deseja exibir na caixa de ferramentas. |
[ToolboxItem(false)] Aplicado ao controle TemplateOwner em Exemplo de Modelo de Controle de Servidor. |
|
Atributo em Tempo de Design. Especifica o nome da propriedade que é verificada por um controle de validação.Geralmente isso é a propriedade cujo valor é fornecido pelo usuários em tempo de execução, como uma propriedade Text do controle TextBox.No designer visual, a caixa de diálogo que permite aos desenvolvedores de página selecionar o destino das listas de propriedades de um controle de validação especificadas com ValidationPropertyAttribute de controles na página. |
[ValidationProperty("Text")] |
Atributos Aplicados às Propriedades Públicas
Atributo |
Exemplo |
|---|---|
|
Atributo em Tempo de Design. Especifica se é significativo vincular dados a uma propriedade.Em um criador visual, o pesquisador de propriedades pode exibir as propriedades vinculáveis de um controle em uma caixa de diálogo.(Por exemplo, em Visual Studio, propriedades vinculáveis são exibidas na caixa de diálogo de DataBindings.) Se uma propriedade não estiver marcada com esse atributo, o pesquisador de propriedades inferirá o valor como Bindable(false). |
[Bindable(true)] Aplicado à propriedade Text do controle exemplo WelcomeLabel em Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado. |
|
Atributo em Tempo de Design. Especifica se uma propriedade deve ser exibida na propriedade designer Visual do navegador.Aplicar Browsable(false) a uma propriedade que você não deseja que seja exibida no navegador da propriedade.O valor padrão, Browsable(true), será inferida pelo navegador da propriedade quando uma propriedade não estiver marcada com esse atributo. |
[Browsable(false)] Aplicado à propriedade Template do controle exemplo VacationHome em Exemplo de Modelo de Controle de Servidor. |
|
Atributo em Tempo de Design. Especifica como categorizar a propriedade no pesquisador de propriedades de um criador visual.Por exemplo, Category("Appearance") informa o navegador da propriedade para exibir a propriedade na categoria Aparência quando o desenvolvedor de página usar modo de categoria no navegador da propriedade.Você pode especificar uma string argumento correspondente a uma categoria no navegador da propriedade existente ou criar sua própria categoria. |
[Category("Appearance")] Aplicado à propriedade Text do controle exemplo WelcomeLabel em Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado. |
|
Atributo em Tempo de Design. Especifica um valor padrão de uma propriedade.Este valor deve ser igual ao valor padrão que você retornar do assessor de propriedade (Getter).Em alguns designers visuais como o Visual Studio, o atributo DefaultValueAttribute permite que um desenvolvedor de página redefina um valor da propriedade para seu padrão usando o comando Reset no menu de atalho. |
[DefaultValue("")] Aplicado à propriedade Text do controle exemplo WelcomeLabel em Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado. |
|
Atributo em Tempo de Design. Especifica uma breve descrição da propriedade.Em um designer visual como o Visual Studio, o navegador de propriedades exibe a descrição da propriedade selecionada, geralmente na parte inferior da janela. |
[Description("The welcome message text.")] Aplicado à propriedade Text do controle exemplo WelcomeLabel em Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado. |
DesignerSerializationVisibilityAttribute Atributo em Tempo de Design. Especifica se deve-se serializar uma propriedade ou seu conteúdo (como subpropriedades ou itens de coleção) que são definidos em tempo de design.O argumento do construtor do atributo é um valor da enumeração DesignerSerializationVisibility.O valor padrão, Visible, é inferido quando este atributo não é aplicado, e o valor da propriedade é serializado. |
[DesignerSerializationVisibility (DesignerSerializationVisibility.Content)] Aplicado à propriedade Author do controle exemplo Book em Exemplo das propriedades de controle do servidor. |
|
Atributo em Tempo de Design. Associa um editor personalizado UITypeEditor com uma propriedade ou tipo de propriedade.Se esse atributo for aplicado ao tipo, ele não tem que ser aplicado a uma propriedade de tipo. |
[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))] Aplicado à propriedade Contacts do controle exemplo QuickContacts em Exemplo da propriedade de coleção do controle da Web. |
|
Atributo em Tempo de Design. Especifica se o nome da propriedade aparece em uma editor de código-fonte da lista do IntelliSense.Esse atributo também pode ser aplicado a métodos e eventos.O argumento do construtor do atributo é um valor da enumeração EditorBrowsableState.O valor padrão, Always, é inferido quando este atributo não é aplicado. |
[EditorBrowsableAttribute (EditorBrowsableState.Never)] Aplique o atributo mostrado no exemplo anterior para ocultar um membro de IntelliSense. |
|
Atributo em tempo de design e em tempo de análise. Especifica se uma propriedade pode participar do dispositivo e filtragem do navegador.A filtragem permite que um desenvolvedor de página especifique valores diferentes de propriedades para navegadores diferentes em uma única declaração de controle.Por exemplo, um desenvolvedor de página pode usar a filtragem para definir valores diferentes para a propriedade Text de um controle Label, como mostra a seguinte sintaxe: "UP" e "IE" são filtros do navegador.O valor padrão, Filterable(true), é inferido quando este atributo não é aplicado. |
[Filterable(false)] Aplique o atributo mostrado no exemplo anterior para excluir uma propriedade do dispositivo e filtragem do navegador. |
|
Atributo em Tempo de Design. Especifica se é significativo localizar a propriedade.Quando uma propriedade estiver marcada Localizable(true), o valor da propriedade é armazenado em um arquivo de recurso.O valor padrão, Localizable(false), é inferido quando este atributo não é aplicado. |
[Localizable(true)] Aplicado à propriedade Text do controle exemplo WelcomeLabel em Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado. |
|
Atributo em Tempo de Design. Especifica que em um navegador de propriedade, as alterações feitas em uma subpropriedade devem ser propagadas para a propriedade Pai. |
[NotifyParentProperty(true)] Aplicada às propriedades FirstName, LastName e MiddleName do tipo Author definido em Exemplo das propriedades de controle do servidor. |
|
Atributo em Tempo de Design. Especifica se deve manter uma propriedade como um atributo na marca do controle ou conteúdo aninhado dentro das marcas de controle.O argumento do construtor do atributo é um valor da enumeração PersistenceMode. |
[PersistenceMode(PersistenceMode.InnerProperty)] Aplicado à propriedade Author do controle exemplo Book em Exemplo das propriedades de controle do servidor. |
|
Atributo em tempo de design e em tempo de análise. Especifica o tipo de contêiner de nomeação para uma propriedade que retorna uma interface ITemplate. |
[TemplateContainer(typeof(CustomTemplateContainer))] Aplique o atributo mostrado no exemplo anterior para especificar que a propriedade ITemplate é representada pela classe CustomTemplateContainer. |
|
Atributo em tempo de design e em tempo de análise. Especifica se uma propriedade de modelo permite a criação de uma ou várias instâncias.Se uma propriedade de modelo não é estendida com o atributo TemplateInstanceAttribute, várias instâncias são o padrão. |
[TemplateInstance(TemplateInstance.Single)] Aplicar o atributo mostrado no exemplo anterior para especificar que apenas uma instância de uma propriedade de modelo pode ser criada. |
|
Atributo em Tempo de Análise. Especifica se um mebro de controle pode ser afetado por temas ou capas de controle.Por padrão, todas as propriedades expostas por um controle podem ter temas aplicados se o próprio tipo de controle pode ter temas aplicados. |
[Themeable(false)] Aplique o atributo mostrado no exemplo anterior para impedir que um controle e todos os seus membros sejam afetados por temas ou capas de controle. |
|
Atributo em tempo de design, em tempo de análise e em tempo de execução. Associa um conversor de tipos com uma propriedade ou tipo de propriedade.Conversores de tipo executam conversões de uma representação string e vice-versa um determinado tipo. |
[TypeConverter(typeof(AuthorConverter))] Aplicadas ao tipo Author definido em Exemplo das propriedades de controle do servidor. |
|
Atributo em tempo de design e em tempo de execução. Especifica que uma propriedade de string representa um valor URL, que permite que você associe um construtor URL à propriedade. |
[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)] Aplicar para definir um filtro de arquivo específico para arquivos ASP.NET e permitir caminhos absolutos e relativos. |
Atributos Aplicados aos Membros de Eventos
Os principais atributos aplicados aos membros do evento são três atributos de time de design: BrowsableAttribute, CategoryAttribute, e DescriptionAttribute. Esses atributos também são aplicados às propriedades e estão descritos na tabela anterior.Para um exemplo de código, consulte o evento Submit no exemplo controle Register em Exemplo de Controle Web de Composição.
Consulte também
Tarefas
Explicação Passo a Passo: Desenvolvendo e Usando um Controle de Servidor Personalizado