Attribute und Entwurfszeitunterstützung

Erweiterungen der Entwurfszeitunterstützung werden i. d. R. in Code implementiert, der unabhängig vom Code für eine Komponente vorhanden ist. Ein Vielzahl von Attributen wird verwendet, um Anbietern von Entwurfszeitunterstützung einen Typ oder einen einzelnen Member eines Typs zuzuordnen.

Attribute für das Zuordnen von Entwurfszeitunterstützung

Ein DesignerAttribute ordnet einem Designer einen Typ zu. Ein TypeConverterAttribute ordnet einen Typ oder einen Typmember einem Typkonverter zu. Ein EditorAttribute ordnet einen Typ oder einen Typmember einem Typ-Editor für Benutzeroberflächen zu.

Attribute zum Anpassen der Initialisierung von Komponenten

Sie können ein DefaultValueAttribute auf eine Eigenschaft anwenden und damit einen Standardwert angeben, auf den die Eigenschaft festgelegt werden soll, wenn eine Komponente zur Entwurfszeit geladen wird. Ein DefaultValueAttribute überschreibt einen Wert, der zur Entwurfszeit durch den Initialisierungscode der Komponente festgelegt wird. Ein vom Designer festgelegter Wert wird durch das Attribut jedoch nicht überschrieben.

Attribute zum Anpassen des Verhaltens von Eigenschaftenfenstern

Sie können angeben, ob eine Eigenschaft oder ein Ereignis in einem Eigenschaftenfenster aufgelistet werden soll, indem Sie das BrowsableAttribute auf das entsprechende Element anwenden. Darüber hinaus können Sie mit einem Designer, der die IDesignerFilter-Schnittstelle implementiert, die Gruppe von Eigenschaften und Ereignissen ändern, die dem Eigenschaftenfenster zur Entwurfszeit verfügbar gemacht wird. Die Kategorie, unter der eine Eigenschaft oder ein Ereignis im Eigenschaftenfenster aufgelistet werden soll, legen Sie fest, indem Sie das CategoryAttribute auf die Eigenschaft bzw. das Ereignis anwenden. Sie können eine Beschreibung angeben, die für eine Eigenschaft oder ein Ereignis im Eigenschaftenfenster angezeigt werden soll, in dem Sie ein DescriptionAttribute auf die Eigenschaft bzw. das Ereignis anwenden.

Durch Anwenden von DesignOnlyAttribute auf eine Eigenschaft können Sie angeben, ob die entsprechende Eigenschaft nur zur Entwurfszeit festgelegt werden kann. Sie legen fest, ob eine Eigenschaft schreibgeschützt ist oder ob der Lese-/Schreibzugriff möglich sein soll, indem Sie das ReadOnlyAttribute auf die Eigenschaft anwenden.

Wenn eine Eigenschaft im Eigenschaftenfenster mit ihrem in Klammern aufgeführten Namen aufgelistet werden soll, wenden Sie das ParenthesizePropertyNameAttribute mit dem Wert true auf die Eigenschaft an.

Geben Sie an, ob eine Eigenschaft mit geschachtelten bzw. untergeordneten Eigenschaften benachrichtigt werden soll, wenn sich der Wert einer dieser geschachtelten Eigenschaften ändert, indem Sie ein NotifyParentPropertyAttribute auf die geschachtelte Eigenschaft anwenden, die die Benachrichtigung auslösen soll.

Wenn entweder die Eigenschaften für eine Komponente, keine Eigenschaften oder die Designeransicht aktualisiert werden sollen, wenden Sie das RefreshPropertiesAttribute mit dem entsprechenden RefreshProperties-Wert auf die Eigenschaft bzw. das Ereignis an.

Attribute zum Anpassen des Serialisierungsverhaltens zur Entwurfszeit

Sie können angeben, ob die Werte einer Eigenschaft oder die Werte einer Auflistungseigenschaft serialisiert werden, indem Sie das DesignerSerializationVisibilityAttribute mit dem entsprechenden DesignerSerializationVisibility-Enumerationswert auf die Eigenschaft anwenden. Visual Studio bietet umfassende Unterstützung für diese Aufgabe. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Serialisieren der Auflistungen von Standardtypen mit dem DesignerSerializationVisibilityAttribute und Exemplarische Vorgehensweise: Serialisieren der Auflistungen von Standardtypen mit dem DesignerSerializationVisibilityAttribute und Exemplarische Vorgehensweise: Serialisieren der Auflistungen von Standardtypen mit dem DesignerSerializationVisibilityAttribute und Exemplarische Vorgehensweise: Serialisieren der Auflistungen von Standardtypen mit dem DesignerSerializationVisibilityAttribute.

Wenn ein Typ serialisiert werden soll, wenden Sie das SerializableAttribute auf den Typ an. Für eine benutzerdefinierte Serialisierung implementieren Sie die ISerializable-Schnittstelle, oder stellen Sie ein benutzerdefiniertes Serialisierungsprogramm bereit. Weitere Informationen zur Serialisierung finden Sie unter Serialization.

Weitere Informationen über häufig verwendete Entwurfszeitattribute finden Sie unter Entwurfszeitattribute für Komponenten.

Anwenden von Attributen

Entwurfszeitattribute werden auf Eigenschaften, Ereignisse, Klassen und auch auf Assemblys angewendet. Im folgenden Codebeispiel werden Attribute auf eine Klasse und anschließend auf Eigenschaften und Ereignisse angewendet.

' The attribute is the element in angle brackets, and the parameters 
' in the attribute syntax are arguments of the constructor 
' of the attribute class.
' 
' Attributes applied at the class level.
<DefaultEvent("ValueChanged"), _
DefaultProperty("Number")> _
Public Class MyControl
   Inherits Control   
   ...
   ' Attribute applied to a property.
   <DefaultValue(False)> _
   Public Shadows ReadOnly Property TabStop() As Boolean
      ...
   End Property
   
   ' Attribute applied to a property.
   <CategoryAttribute("Data")> _
   Public ReadOnly Property Number() As Integer
      ...
   End Property 
   
   ' Attribute applied to an event.
   <Description("Raised when the Value displayed changes.")>  _
   Public Event ValueChanged As EventHandler
   ...
End Class

// The attribute is the element in brackets, and the parameters in 
// the attribute syntax are arguments of the constructor 
// of the attribute class.
// 
// Attributes applied at the class level.
[DefaultEvent("ValueChanged")]
[DefaultProperty("Number")]
public class MyControl : Control {
   ...
   // Attribute applied to a property.
   [DefaultValue(false)]
   public new bool TabStop {...
   }

   // Attribute applied to a property.
   [CategoryAttribute("Data")]
   public int Number {...}

   // Attribute applied to an event.
   [Description("Raised when the Value displayed changes.")]
   public event EventHandler ValueChanged;
}

Attributklassen werden gemäß der Konvention immer nach dem Muster AttributeNameAttribut benannt. Der System.ComponentModel-Namespace enthält viele Basisattributklassen.

Entwurfszeitattribute und Vererbung

Wenn Sie eine Komponente oder ein Steuerelement von einer Basiskomponente ableiten, die über Entwurfszeitattribute verfügt, erbt diese Komponente die Entwurfszeitfunktionen der Basisklasse. Wenn die Basisfunktionen dem gewünschten Zweck entsprechen, müssen Sie die Attribute nicht erneut anwenden. Sie können jedoch Attribute desselben Typs überschreiben oder zusätzliche Attribute auf die abgeleitete Komponente anwenden. Im folgenden Codefragment wird ein benutzerdefiniertes Steuerelement gezeigt, das die von Control geerbte Text-Eigenschaft überschreibt, indem es das in der Basisklasse angewendete BrowsableAttribute-Attribut überschreibt.

Public Class MyControl
   Inherits Control
   ' The base class has [Browsable(true)] applied to the Text property.
   <Browsable(False)>  _
   Public Overrides Property [Text]() As String
      ...
   End Property 
   ...
End Class

public class MyControl : Control {
// The base class has [Browsable(true)] applied to the Text property.
[Browsable(false)]
 public override string Text {...}
...
}

Anwenden eines Typkonverters, eines Typ-Editors für Benutzeroberflächen oder eines Designerattributs

Wenn Sie einen Anbieter für die Entwurfszeitunterstützung einem Typ oder Typmember zuordnen möchten, wenden Sie den entsprechenden Attributtyp in der Zeile über der Klassen- bzw. der Memberdeklaration an. Der folgende Beispielcode zeigt ein auf einen Typ angewendetes TypeConverterAttribute.

<TypeConverter(GetType(MyColorConverter)), _
Editor(GetType(MyColorEditor), GetType(UITypeEditor))> _
Structure MyColor
   ...
End Structure

[ TypeConverter(typeof(MyColorConverter))]
[ Editor(typeof(MyColorEditor), typeof(UITypeEditor))] 
struct MyColor {...}

Wenn dem Typ einer Eigenschaft kein Typkonverter oder Typ-Editor für Benutzeroberflächen zugeordnet ist oder wenn Sie den dem Typ zugeordneten Standardkonverter bzw. -Editor überschreiben möchten, können Sie ein Attribut direkt auf die Eigenschaft selbst anwenden. Sie ordnen einer Eigenschaft einen Typkonverter zu, indem Sie ein TypeConverterAttribute auf die Eigenschaftsdeklaration anwenden, wie im folgenden Codebeispiel dargestellt.

<TypeConverter(GetType(PointConverter))> _
Public Property MyLocation() As Point
   ...
End Property       

[ TypeConverter(typeof(PointConverter))]
        public Point MyLocation {...}  

Sie ordnen einen Typ-Editor für Benutzeroberflächen einer Eigenschaft zu, indem Sie ein EditorAttribute auf die Eigenschaft anwenden, wie im folgenden Codebeispiel dargestellt.

<Editor(GetType(FlashTrackBarDarkenByEditor), _
GetType(UITypeEditor))>  _
Public Property DarkenBy() As Byte
   ...
End Property

[ Editor(typeof(FlashTrackBarDarkenByEditor), typeof(UITypeEditor))]
        public byte DarkenBy {...}

Ein Designer kann einem Typ, nicht jedoch einer Eigenschaft zugeordnet werden. Sie ordnen einen Designer einem Typ zu, indem Sie ein DesignerAttribute direkt über der Klassendeklaration anwenden, wie im folgenden Codebeispiel dargestellt.

<Designer(GetType(HelpLabel.HelpLabelDesigner))> _
Public Class HelpLabel
   Inherits System.Windows.Forms.Control
   Implements System.ComponentModel.IExtenderProvider
   ...
End Class

    [Designer(typeof(HelpLabel.HelpLabelDesigner))]
    public class HelpLabel : System.Windows.Forms.Control, System.ComponentModel.IExtenderProvider {...}

<Designer("System.Windows.Forms.Design.DocumentDesigner, System.Design")>  _
Public Class MyForm
   Inherits Form
   ...
End Class

[Designer("System.Windows.Forms.Design.DocumentDesigner, System.Design")]
public class MyForm : Form {...}

Entwurfszeitattribut auf Assemblyebene

ASP.NET stellt ein Attribut auf Assemblyebene (System.Web.UI.TagPrefixAttribute) zur Verfügung. Damit können Entwickler von Steuerelementen ein Tagpräfix für ein ASP.NET-Steuerelement festlegen. Das Tagpräfix wird von Visual Studio automatisch in die Register-Direktive für das Steuerelement eingefügt, sodass das Steuerelement deklarativ auf der Seite mit dem vordefinierten Tagpräfix (<Tagpräfix:Steuerelementname runat = server />) verwendet werden kann.

Im folgenden Codebeispiel wird gezeigt, wie das TagPrefixAttribute angewendet wird. Das erste Argument für den Konstruktor des Attributs gibt den Namespace und das zweite das Tagpräfix an.

<assembly: TagPrefix("SimpleControls", "simple")>
Namespace SimpleControls
   <Designer("SimpleControl.Design.SimpleDesigner, SimpleControl")>  _
   Public Class SimpleControl
      Inherits System.Web.UI.WebControls.WebControl
      ...
   End Class 
End Namespace

[ assembly:TagPrefix("SimpleControls", "simple") ]
namespace SimpleControls {
    [
        Designer("SimpleControl.Design.SimpleDesigner, SimpleControl")
    ]
    public class SimpleControl : System.Web.UI.WebControls.WebControl {}
}

Siehe auch

Aufgaben

Gewusst wie: Implementieren eines Typkonverters

Gewusst wie: Implementieren eines Typ-Editors für die Benutzeroberfläche

Gewusst wie: Anwenden von Attributen auf Windows Forms-Steuerelemente

Konzepte

Attribute in Windows Forms-Steuerelementen

Entwurfszeitattribute für Komponenten

Weitere Ressourcen

Erweitern der Entwurfszeitunterstützung

Benutzerdefinierte Designer