Attributi di metadati per controlli server personalizzati

Aggiornamento: novembre 2007

Gli attributi di metadati vengono applicati ai controlli server e ai relativi membri per fornire informazioni utilizzate da strumenti di progettazione, parser di pagine ASP.NET, runtime ASP.NET e Common Language Runtime. Gli attributi della fase di progettazione facilitano il lavoro dello sviluppatore in fase di progettazione quando utilizza il controllo nella finestra di progettazione visiva. Gli attributi della fase di progettazione non modificano la funzionalità di un controllo durante una richiesta della pagina. Gli attributi della fase di analisi del controllo vengono utilizzati dal parser di pagine ASP.NET durante la lettura della sintassi dichiarativa del controllo in una pagina. Gli attributi delle fasi di analisi ed esecuzione sono indispensabili per il funzionamento di un controllo in una pagina.

In questa sezione vengono descritti gli attributi di metadati più comunemente applicati ai controlli, alle proprietà pubbliche e agli eventi.

Attributi applicati a un controllo

Attributo	Esempio
AspNetHostingPermissionAttribute Attributo di protezione dall'accesso di codice in fase di compilazione JIT. Questo attributo è necessario per garantire che il codice di collegamento al controllo disponga delle autorizzazioni di protezione appropriate. La classe Control è contrassegnata da due attributi di protezione dall'accesso di codice in fase di compilazione JIT: AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal) e AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal). È necessario applicare il primo attributo al controllo, ma non il secondo, perché una richiesta di ereditarietà è transitiva e rimane attiva per le classi derivate. Per ulteriori informazioni, vedere SecurityAction.	[AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)] Applicato al controllo di esempio WelcomeLabel in Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato.
ControlBuilderAttribute Attributo della fase di analisi. Questo attributo associa un generatore di controlli personalizzati al controllo stesso. È necessario applicare questo attributo solo se si desidera utilizzare un generatore di controlli personalizzato per modificare la logica predefinita utilizzata dal parser di pagine per l'analisi della sintassi dichiarativa del controllo. Se si desidera solamente specificare se il contenuto incluso nei tag del controllo corrisponde a proprietà o a controlli figlio, utilizzare ParseChildrenAttribute, descritto più avanti nella tabella, anziché un generatore di controlli personalizzato.	[ControlBuilder(typeof(MyControlBuilder))]
ControlValuePropertyAttribute Attributo delle fasi di progettazione ed esecuzione. Questo attributo consente di specificare la proprietà utilizzata come valore predefinito per un controllo. L'applicazione di questo attributo attiva un controllo da utilizzare come parametro in una query in fase di esecuzione e definisce il valore predefinito a cui è associato un oggetto ControlParameter in fase di esecuzione.	[ControlValueProperty("Text")]
DefaultEventAttribute Attributo della fase di progettazione. Questo attributo specifica l'evento predefinito per il controllo nella finestra di progettazione visiva. In molte finestre di progettazione visiva, quando lo sviluppatore di pagine fa doppio clic sul controllo nell'area di progettazione verrà aperto l'editor di codice, con il cursore posizionato in corrispondenza del gestore eventi per l'evento predefinito.	[DefaultEvent("Submit")] Applicato al controllo di esempio Register in Esempio di controllo Web composito.
DefaultPropertyAttribute Attributo della fase di progettazione. La proprietà specificata in questo attributo viene evidenziata nel Visualizzatore proprietà della finestra di progettazione visiva quando lo sviluppatore della pagina seleziona il controllo nell'area di progettazione.	[DefaultProperty("Text")] Applicato al controllo di esempio WelcomeLabel in Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato.
DesignerAttribute Attributo della fase di progettazione. Questo attributo consente di specificare la classe di progettazione associata a un controllo. Una classe di progettazione del controllo è responsabile dell'aspetto e del comportamento del controllo associato in un'area di progettazione della finestra di progettazione visiva.	[Designer(typeof(SimpleCompositeControlDesigner))] Applicato ai controlli di esempio in Procedura dettagliata: creazione di una finestra Progettazione controlli di base per un controllo server Web
ParseChildrenAttribute Attributo della fase di analisi. Questo attributo consente di specificare se i contenuti inclusi nei tag del controllo corrispondono a proprietà o a controlli figlio. La classe Control viene contrassegnata come ParseChildren(false): ciò significa che il parser di pagine interpreta il contenuto incluso nei tag del controllo come controlli figlio. La classe WebControl viene contrassegnata come ParseChildren(true): ciò significa che il parser di pagine interpreta il contenuto incluso nei tag del controllo come proprietà. È necessario applicare questo attributo solamente se si desidera modificare la logica specificata nell'attributo ParseChildrenAttribute della classe WebControl.	[ParseChildren(true, "Contacts")] Applicato al controllo di esempio QuickContacts in Esempio di proprietà Collection di Web Control.
PersistChildrenAttribute Attributo della fase di progettazione. Questo attributo consente di specificare se una finestra di progettazione visiva deve mantenere i controlli figlio o le proprietà inclusi nei tag del controllo quando il controllo viene utilizzato in modo dichiarativo in una pagina. La classe Control viene contrassegnata come PersistChildren(true): ciò significa che la finestra di progettazione mantiene i controlli figlio inclusi nei tag del controllo. La classe WebControl viene contrassegnata come PersistChildren(false): ciò significa che la finestra di progettazione mantiene le proprietà sotto forma di attributi inclusi nei tag del controllo.	[PersistChildren(false)] Applicato alla classe WebControl e appropriato per la maggior parte dei controlli che derivano da questa classe. Tuttavia, controlli contenitore come Panel che mantengono i controlli figlio inclusi nei tag vengono contrassegnati come PersistChildren(true) e ParseChildren(false).
ThemeableAttribute Attributo della fase di analisi. Questo attributo consente di specificare se su un controllo possono avere effetto temi o interfacce del controllo. Se un tipo di controllo viene contrassegnato in modo da indicare che non possono esservi applicati temi, analogamente questi non avranno effetto su tutti i membri del controllo.	[Themeable(false)] Applicare l'attributo illustrato nell'esempio precedente per impedire che su un controllo e su tutti i relativi membri abbiano affetto temi o interfacce del controllo.
ToolboxDataAttribute Attributo della fase di progettazione. Questo attributo consente di specificare il formato del codice generato per il tag nella finestra di progettazione visiva quando il controllo viene generato con la casella degli strumenti.	[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"] Applicato al controllo di esempio WelcomeLabel in Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato.
ToolboxItemAttribute Attributo della fase di progettazione. Questo attributo consente di specificare se una finestra di progettazione visiva deve visualizzare un controllo o un componente nella casella degli strumenti. Per impostazione predefinita, i controlli vengono sempre visualizzati nella casella degli strumenti. È necessario applicare questo attributo solamente a un controllo, come il proprietario di una proprietà del modello, che non si desidera visualizzare nella casella degli strumenti.	[ToolboxItem(false)] Applicato al controllo TemplateOwner in Esempio di controllo server basato su modelli.
ValidationPropertyAttribute Attributo della fase di progettazione. Questo attributo consente di specificare il nome della proprietà verificata da un controllo di convalida. In genere, si tratta della proprietà il cui valore viene fornito dagli utenti in fase di esecuzione, come, ad esempio, una proprietà Text del controllo TextBox. In una finestra di progettazione visiva, nella finestra di dialogo che consente agli sviluppatori di pagine di selezionare la destinazione di un controllo di convalida vengono elencate le proprietà specificate in ValidationPropertyAttribute dai controlli nella pagina.	[ValidationProperty("Text")]

Attributi applicati alle proprietà pubbliche

Attributo	Esempio
BindableAttribute Attributo della fase di progettazione. Questo attributo consente di specificare se è rilevante associare i dati a una proprietà. In una finestra di progettazione visiva, il Visualizzatore proprietà è in grado di visualizzare le proprietà associabili del controllo in una finestra di dialogo. Ad esempio, in Visual Studio le proprietà associabili vengono visualizzate nella finestra di dialogo DataBindings. Se una proprietà non viene contrassegnata con l'attributo, il Visualizzatore proprietà deduce che tale valore deve essere Bindable(false).	[Bindable(true)] Applicato alla proprietà Text del controllo di esempio WelcomeLabel in Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato.
BrowsableAttribute Attributo della fase di progettazione. Questo attributo consente di specificare se una proprietà deve essere visualizzata in un Visualizzatore proprietà della finestra di progettazione visiva. Applicare Browsable(false) a una proprietà che non si desidera visualizzare nel Visualizzatore proprietà. Il valore predefinito, Browsable(true), viene dedotto dal Visualizzatore proprietà quando una proprietà non è contrassegnata con l'attributo.	[Browsable(false)] Applicato alla proprietà Template nel controllo di esempio VacationHome in Esempio di controllo server basato su modelli.
CategoryAttribute Attributo della fase di progettazione. Questo attributo consente di specificare come definire le categorie della proprietà nel Visualizzatore proprietà della finestra di progettazione visiva. Ad esempio, Category("Appearance") segnala al Visualizzatore proprietà di visualizzare la proprietà nella categoria Aspetto quando lo sviluppatore di pagine utilizza la visualizzazione per categorie nel Visualizzatore proprietà. È possibile specificare un argomento stringa corrispondente a una categoria presente nel Visualizzatore proprietà oppure creare la propria categoria.	[Category("Appearance")] Applicato alla proprietà Text del controllo di esempio WelcomeLabel in Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato.
DefaultValueAttribute Attributo della fase di progettazione. Questo attributo consente di specificare un valore predefinito per una proprietà. Il valore deve essere uguale al valore predefinito restituito dalla funzione di accesso della proprietà (metodo per il richiamo). In alcune finestre di progettazione visiva, come Visual Studio, l'attributo DefaultValueAttribute consente a uno sviluppatore di pagine di reimpostare un valore della proprietà sul valore predefinito utilizzando il comando Reimposta nel menu di scelta rapida.	[DefaultValue("")] Applicato alla proprietà Text del controllo di esempio WelcomeLabel in Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato.
DescriptionAttribute Attributo della fase di progettazione. Questo attributo consente di specificare una breve descrizione della proprietà. In una finestra di progettazione visiva, come, ad esempio, Visual Studio, il Visualizzatore proprietà visualizza la descrizione della proprietà selezionata, in genere nella parte inferiore della finestra.	[Description("The welcome message text.")] Applicato alla proprietà Text del controllo di esempio WelcomeLabel in Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato.
DesignerSerializationVisibilityAttribute Attributo della fase di progettazione. Questo attributo consente di specificare se serializzare una proprietà o i contenuti della stessa, quali sottoproprietà o elementi dell'insieme, impostati in fase di progettazione. L'argomento del costruttore dell'attributo è un valore dell'enumerazione DesignerSerializationVisibility. Il valore predefinito, Visible, è implicito quando l'attributo non viene applicato e il valore della proprietà viene serializzato.	[DesignerSerializationVisibility (DesignerSerializationVisibility.Content)] Applicato alla proprietà Author del controllo di esempio Book in Esempio di proprietà dei controlli server.
EditorAttribute Attributo della fase di progettazione. Questo attributo associa un editor UITypeEditor personalizzato a una proprietà o a un tipo di proprietà. Se l'attributo è applicato al tipo, non sarà necessario applicarlo a una proprietà di quel tipo.	[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))] Applicato alla proprietà Contacts del controllo di esempio QuickContacts in Esempio di proprietà Collection di Web Control.
EditorBrowsableAttribute Attributo della fase di progettazione. Questo attributo consente di specificare se il nome della proprietà compare in un elenco IntelliSense dell'editor standard. È possibile applicare questo attributo anche a metodi ed eventi. L'argomento del costruttore dell'attributo è un valore dell'enumerazione EditorBrowsableState. Il valore predefinito, Always, è implicito quando l'attributo non viene applicato.	[EditorBrowsableAttribute (EditorBrowsableState.Never)] Applica l'attributo illustrato nell'esempio precedente per nascondere un membro in IntelliSense.
FilterableAttribute Attributo in fase di progettazione e analisi. Questo attributo consente di specificare se una proprietà può contribuire alle operazioni di filtro di dispositivi e browser. I filtri consentono a uno sviluppatore di pagine di specificare diversi valori delle proprietà in base al tipo di browser nella dichiarazione di un solo controllo. Ad esempio, uno sviluppatore di pagine può utilizzare operazioni di filtro per impostare valori diversi per la proprietà Text di un controllo Label, come illustrato nella sintassi seguente: <asp:Label UP:Text="Hello" and IE:Text="Welcome to my site" /> "UP" e "IE" sono filtri del browser. Il valore predefinito Filterable(true) è implicito quando l'attributo non viene applicato.	[Filterable(false)] Applicare l'attributo illustrato nell'esempio precedente per escludere una proprietà dalle operazioni di filtro di dispositivi e browser.
LocalizableAttribute Attributo della fase di progettazione. Questo attributo consente di specificare se è rilevante localizzare la proprietà. Quando una proprietà viene contrassegnata come Localizable(true), il valore della proprietà viene archiviato in un file di risorse. Il valore predefinito, Localizable(false), è implicito quando l'attributo non è applicato.	[Localizable(true)] Applicato alla proprietà Text del controllo di esempio WelcomeLabel in Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato.
NotifyParentPropertyAttribute Attributo della fase di progettazione. Questo attributo consente di specificare che, in un Visualizzatore proprietà, le variazioni di una sottoproprietà devono essere propagate alla proprietà padre.	[NotifyParentProperty(true)] Applicato alle proprietà FirstName, LastName e MiddleName del tipo Author definito in Esempio di proprietà dei controlli server.
PersistenceModeAttribute Attributo della fase di progettazione. Questo attributo consente di specificare se mantenere una proprietà come attributo del tag del controllo o come contenuto nidificato nei tag del controllo. L'argomento del costruttore dell'attributo è un valore dell'enumerazione PersistenceMode.	[PersistenceMode(PersistenceMode.InnerProperty)] Applicato alla proprietà Author del controllo di esempio Book in Esempio di proprietà dei controlli server.
TemplateContainerAttribute Attributo delle fasi di progettazione e analisi. Questo attributo consente di specificare il tipo di contenitore di denominazione di una proprietà che restituisce un'interfaccia ITemplate.	[TemplateContainer(typeof(CustomTemplateContainer))] Applicare l'attributo illustrato nell'esempio precedente per specificare che la proprietà ITemplate viene rappresentata dalla classe CustomTemplateContainer.
TemplateInstanceAttribute Attributo delle fasi di progettazione e analisi. Questo attributo consente di specificare se una proprietà di modello consente la creazione di una o più istanze. Se una proprietà di modello non viene estesa con l'attributo TemplateInstanceAttribute, l'impostazione predefinita è costituita da più istanze.	[TemplateInstance(TemplateInstance.Single)] Applicare l'attributo illustrato nell'esempio precedente per specificare che è possibile creare una sola istanza di una proprietà di modello.
ThemeableAttribute Attributo della fase di analisi. Questo attributo consente di specificare se sul membro di un controllo possono avere effetto temi o interfacce del controllo. Per impostazione predefinita, è possibile applicare temi a tutte le proprietà esposte da un controllo se questi sono applicabili al tipo di controllo stesso.	[Themeable(false)] Applicare l'attributo illustrato nell'esempio precedente per impedire che sul membro di un controllo abbiano affetto temi o interfacce del controllo.
TypeConverterAttribute Attributo delle fasi di progettazione, analisi ed esecuzione. Associa un convertitore di tipi a una proprietà o a un tipo di proprietà. I convertitori di tipi eseguono le conversioni da una rappresentazione sotto forma di stringa a un determinato tipo e viceversa.	[TypeConverter(typeof(AuthorConverter))] Applicato al tipo Author definito in Esempio di proprietà dei controlli server.
UrlPropertyAttribute Attributo delle fasi di progettazione ed esecuzione. Questo attributo consente di specificare che la proprietà stringa rappresenta un valore URL ed è quindi possibile associare un generatore di URL alla proprietà.	[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)] Applicare l'attributo per impostare un filtro di file specifico per i file ASP.NET e consentire percorsi assoluti e relativi.

Attributi applicati a membri dell'evento

Gli attributi principali applicati a membri dell'evento sono tre attributi della fase di progettazione: BrowsableAttribute, CategoryAttribute e DescriptionAttribute. Questi attributi vengono applicati anche alle proprietà e sono descritti nella tabella precedente. Per un esempio di codice, vedere l'evento Submit nell'esempio di controllo Register in Esempio di controllo Web composito.

Vedere anche

Attività

Procedura dettagliata: sviluppo e utilizzo di un controllo server personalizzato

Altre risorse

Sviluppo di controlli server ASP.NET personalizzati