Entwurfszeiteigenschaften für benutzerdefinierte Steuerelemente (Windows Forms .NET)

In diesem Artikel erfahren Sie, wie Eigenschaften für Steuerelemente im Windows Forms Visual Designer in Visual Studio behandelt werden.

Jedes Steuerelement erbt viele Eigenschaften von der Basisklasse System.Windows.Forms.Control, z. B.:

• Enabled
• Font
• ForeColor
• Focused
• Visible
• Width

Beim Erstellen eines Steuerelements können Sie neue Eigenschaften definieren und steuern, wie sie im Designer angezeigt werden.

Wichtig

Der Desktopleitfaden zu .NET 7 und .NET 6 ist in Bearbeitung.

Definieren einer Eigenschaft

Alle öffentlichen Eigenschaften mit einer durch ein Steuerelement definierten get-Zugriffsmethode werden automatisch im Visual Studio-Fenster Eigenschaften angezeigt. Wenn die Eigenschaft auch eine set-Zugriffsmethode definiert, kann die Eigenschaft im Fenster Eigenschaften geändert werden. Eigenschaften können jedoch explizit im Fenster Eigenschaften angezeigt oder ausgeblendet werden, indem das BrowsableAttribute angewendet wird. Dieses Attribut verwendet einen einzelnen booleschen Parameter, um anzugeben, ob es angezeigt wird. Weitere Informationen zu Attributen finden Sie unter Attribute (C#) oder Attributübersicht (Visual Basic).

[Browsable(false)]
public bool IsSelected { get; set; }

<Browsable(False)>
Public Property IsSelected As Boolean

[HINWEIS] Komplexe Eigenschaften, die nicht implizit in und aus einer Zeichenfolge konvertiert werden können, erfordern einen Typkonverter.

Serialisierte Eigenschaften

Eigenschaften, die für ein Steuerelement festgelegt sind, werden in die CodeBehind-Datei des Designers serialisiert. Dies geschieht, wenn der Wert einer Eigenschaft auf einen anderen Wert als den Standardwert festgelegt ist.

Wenn der Designer eine Änderung an einer Eigenschaft erkennt, wertet er alle Eigenschaften für das Steuerelement aus und serialisiert alle Eigenschaften, deren Wert nicht mit dem Standardwert für die Eigenschaft übereinstimmt. Der Wert einer Eigenschaft wird in die CodeBehind-Datei des Designers serialisiert. Standardwerte helfen dem Designer, zu bestimmen, welche Eigenschaftswerte serialisiert werden sollen.

Standardwerte

Eine Eigenschaft wird als Standardwert betrachtet, wenn sie entweder das Attribut DefaultValueAttribute anwendet, oder die Eigenschaftsklasse enthält eigenschaftsspezifische Reset- und ShouldSerialize-Methoden. Weitere Informationen zu Attributen finden Sie unter Attribute (C#) oder Attributübersicht (Visual Basic).

Durch Festlegen eines Standardwerts aktivieren Sie Folgendes:

• Die Eigenschaft zeigt im Fenster Eigenschaften an, wenn ihr Standardwert geändert wurde.
• Der Benutzer kann mit der rechten Maustaste auf die Eigenschaft klicken und Zurücksetzen auswählen, um die Eigenschaft auf ihren Standardwert zurückzusetzen.
• Der Designer generiert effizienteren Code.

Wenn eine Eigenschaft einen einfachen Typ verwendet, z. B. einen Grundtyp, kann der Standardwert durch Anwenden des DefaultValueAttribute auf die Eigenschaft festgelegt werden. Eigenschaften mit diesem Attribut beginnen jedoch nicht automatisch mit diesem zugewiesenen Wert. Sie müssen das Sicherungsfeld der Eigenschaft auf denselben Standardwert festlegen. Sie können die Eigenschaft in der Deklaration oder im Konstruktor der Klasse festlegen.

Wenn es sich bei einer Eigenschaft um einen komplexen Typ handelt oder Sie das Zurücksetzungs- und Serialisierungsverhalten des Designers steuern möchten, definieren Sie die Reset<PropertyName>- und ShouldSerialize<PropertyName> Methoden und für die Klasse. Wenn das Steuerelement beispielsweise eine Age-Eigenschaft definiert, werden die Methoden ResetAge und ShouldSerializeAge benannt.

Wichtig

Wenden Sie entweder die DefaultValueAttribute-Eigenschaft an, oder stellen Sie beide Methoden Reset<PropertyName> und ShouldSerialize<PropertyName> bereit. Sie sollten nicht beides verwenden.

Eigenschaften können über das Fenster Eigenschaften auf ihre Standardwerte zurückgesetzt werden, indem Sie mit der rechten Maustaste auf den Eigenschaftennamen klicken und Zurücksetzen auswählen.

Die Verfügbarkeit der Kontextmenüoption Eigenschaften>Rechtsklick>Zurücksetzen ist aktiviert, wenn:

• Die Eigenschaft hat das DefaultValueAttribute-Attribut angewendet, und der Wert der Eigenschaft stimmt nicht mit dem Wert des Attributs überein.
• Die Eigenschaftsklasse definiert eine Reset<PropertyName>-Methode ohne einen ShouldSerialize<PropertyName>.
• Die Eigenschaftsklasse definiert eine Reset<PropertyName> Methode und der ShouldSerialize<PropertyName> gibt "true" zurück.

DefaultValueAttribute

Wenn der Wert einer Eigenschaft nicht mit dem von DefaultValueAttribute bereitgestellten Wert übereinstimmt, wird die Eigenschaft als geändert betrachtet und kann über das Fenster Eigenschaften zurückgesetzt werden.

Wichtig

Dieses Attribut sollte nicht für Eigenschaften verwendet werden, die über entsprechende Reset<PropertyName>- und ShouldSerialize<PropertyName>-Methoden verfügen.

Der folgende Code deklariert zwei Eigenschaften, eine Aufzählung mit einem Standardwert von North und eine ganze Zahl mit dem Standardwert 10.

[DefaultValue(typeof(Directions), "North")]
public Directions PointerDirection { get; set; } = Directions.North;

[DefaultValue(10)]
public int DistanceInFeet { get; set; } = 10;

<DefaultValue(GetType(Directions), "North")>
Public Property PointerDirection As Directions = Directions.North

<DefaultValue(10)>
Public Property DistanceInFeet As Integer = 10

Zurücksetzen und ShouldSerialize

Wie zuvor erwähnt, bieten die Methoden Reset<PropertyName> und ShouldSerialize<PropertyName> die Möglichkeit, nicht nur das Zurücksetzungsverhalten einer Eigenschaft zu leiten, sondern auch zu bestimmen, ob ein Wert geändert wird und in die CodeBehind-Datei des Designers serialisiert werden soll. Beide Methoden arbeiten zusammen, und Sie sollten eine nicht ohne die andere definieren.

Wichtig

Die Methoden Reset<PropertyName> und ShouldSerialize<PropertyName> sollten nicht für eine Eigenschaft erstellt werden, die ein DefaultValueAttribute hat.

Wenn Reset<PropertyName> definiert ist, zeigt das Fenster Eigenschaften eine Kontextmenüoption Zurücksetzen für diese Eigenschaft an. Wenn Zurücksetzen ausgewählt wird, wird die Reset<PropertyName>-Methode aufgerufen. Die Kontextmenüoption Zurücksetzen wird durch die von der ShouldSerialize<PropertyName>-Methode zurückgegebenen Optionen aktiviert oder deaktiviert. Wenn ShouldSerialize<PropertyName>true zurückgibt, zeigt das an, dass sich die Eigenschaft gegenüber ihrem Standardwert geändert hat und in die CodeBehind-Datei serialisiert werden soll und die Kontextmenüoption Zurücksetzen wird aktiviert. Wenn false zurückgegeben wird, ist die Kontextmenüoption Zurücksetzen deaktiviert, und Eigenschaftensatzcode wurde aus dem CodeBehind entfernt.

Tipp

Beide Methoden können und sollten mit privatem Bereich definiert werden, sodass sie nicht die öffentliche API des Steuerelements bilden.

Der folgende Codeausschnitt deklariert eine Eigenschaft mit dem Namen Direction. Das Designerverhalten dieser Eigenschaft wird durch die Methoden ResetDirection und ShouldSerializeDirection gesteuert.

public Directions Direction { get; set; } = Directions.None;

private void ResetDirection() =>
    Direction = Directions.None;

private bool ShouldSerializeDirection() =>
    Direction != Directions.None;

Public Property Direction As Directions = Directions.None

Private Sub ResetDirection()
    Direction = Directions.None
End Sub

Private Function ShouldSerializeDirection() As Boolean
    Return Direction <> Directions.None
End Function

Typkonverter

Während Typkonverter in der Regel einen Typ in einen anderen konvertieren, stellen sie auch Zeichenfolge-zu-Wert-Konvertierung für das Eigenschaftenraster und andere Entwurfszeitsteuerelemente bereit. Die Zeichenfolge-zu-Wert-Konvertierung ermöglicht die Darstellung komplexer Eigenschaften in diesen Entwurfszeitsteuerelementen.

Die meisten integrierten Datentypen (Zahlen, Enumerationen und andere) verfügen über Standardtypkonverter, die Zeichenfolgen-zu-Wert-Konvertierungen bereitstellen und Überprüfungen durchführen. Die Standardtypkonverter befinden sich im System.ComponentModel-Namespace und werden nach dem Typ benannt, der konvertiert wird. Die Konvertertypnamen verwenden das folgende Format: {type name}Converter. Beispiel: StringConverter, TimeSpanConverter und Int32Converter.

Typkonverter werden zur Entwurfszeit mit dem Fenster Eigenschaften umfassend verwendet. Ein Typkonverter kann mithilfe des TypeConverterAttribute auf eine Eigenschaft oder einen Typ angewendet werden.

Das Fenster Eigenschaften verwendet Konverter, um die Eigenschaft als Zeichenfolgenwert anzuzeigen, wenn das TypeConverterAttribute für die Eigenschaft deklariert ist. Wenn das TypeConverterAttribute für einen Typ deklariert wird, verwendet das Fenster Eigenschaften den Konverter für jede Eigenschaft dieses Typs. Der Typkonverter hilft auch beim Serialisieren des Eigenschaftswerts in der CodeBehind-Datei des Designers.

Typ-Editoren

Das Fenster Eigenschaften verwendet automatisch einen Typ-Editor für eine Eigenschaft, wenn der Typ der Eigenschaft ein integrierter oder bekannter Typ ist. Beispielsweise wird ein boolescher Wert als Kombinationsfeld mit True- und False-Werten bearbeitet, und der DateTime-Typ verwendet ein Kalenderdropdown.

Wichtig

Benutzerdefinierte Typ-Editoren haben sich seit .NET Framework geändert. Weitere Informationen finden Sie unter Designeränderungen seit .NET Framework (Windows Forms .NET).