Exemplarische Vorgehensweise: Serialisieren der Auflistungen von Standardtypen mit dem DesignerSerializationVisibilityAttribute

Die benutzerdefinierten Steuerelemente machen manchmal eine Auflistung als Eigenschaft verfügbar. Diese exemplarische Vorgehensweise veranschaulicht, wie Sie mit der DesignerSerializationVisibilityAttribute-Klasse steuern können, wie eine Auflistung zur Entwurfszeit serialisiert wird. Wenn Sie den Content-Wert auf die Auflistungseigenschaft anwenden, ist gewährleistet, dass die Eigenschaft serialisiert wird.

Informationen zum Kopieren des Codes in diesem Thema als einzelne Auflistung finden Sie unter Gewusst wie: Serialisieren von Auflistungen der Standardtypen mit dem DesignerSerializationVisibilityAttribute.

Vorbereitungsmaßnahmen

Für die Durchführung dieser exemplarischen Vorgehensweise benötigen Sie Folgendes:

• Ausreichende Berechtigungen zum Erstellen und Ausführen von Windows Forms-Anwendungsprojekten auf dem Computer, auf dem Visual Studio installiert ist.

Erstellen eines Steuerelements, das über eine serialisierbare Auflistung verfügt

Der erste Schritt besteht darin, ein Steuerelement zu erstellen, das über eine serialisierbare Auflistung als Eigenschaft verfügt. Sie können den Inhalt dieser Auflistung mithilfe des Auflistungs-Editors bearbeiten, den Sie über das Eigenschaftenfenster aufrufen können.

So erstellen Sie ein Steuerelement, das über eine serialisierbare Auflistung verfügt

1. Erstellen Sie ein Windows-Steuerelementbibliothek-Projekt mit dem Namen SerializationDemoControlLib. Weitere Informationen finden Sie unter Windows Control Library-Vorlage.

2. Benennen Sie UserControl1 in SerializationDemoControl um. Weitere Informationen finden Sie unter How to: Rename Identifiers.

3. Legen Sie im Fenster Eigenschaften den Wert der Padding.All-Eigenschaft auf 10 fest.

4. Fügen Sie ein TextBox-Steuerelement in das SerializationDemoControl ein.

5. Wählen Sie das TextBox-Steuerelement aus. Legen Sie im Eigenschaftenfenster die folgenden Eigenschaften fest.

   Eigenschaft	Ändern in
   Multiline	true
   Dock	Fill
   ScrollBars	Vertical
   ReadOnly	true

6. Deklarieren Sie im Code-Editor ein Zeichenfolgenarrayfeld mit dem Namen stringsValue im SerializationDemoControl.

   ' This field backs the Strings property.
    Private stringsValue(1) As String
   

   // This field backs the Strings property.
   private String[] stringsValue = new String[1];
   

           // This field backs the Strings property.
       private:
           array<String^>^ stringsValue;
   
   
   

7. Definieren Sie die Strings-Eigenschaft für das SerializationDemoControl.

' When the DesignerSerializationVisibility attribute has
' a value of "Content" or "Visible" the designer will 
' serialize the property. This property can also be edited 
' at design time with a CollectionEditor.
 <DesignerSerializationVisibility( _
     DesignerSerializationVisibility.Content)> _
 Public Property Strings() As String()
     Get
         Return Me.stringsValue
     End Get
     Set(ByVal value As String())
         Me.stringsValue = Value

         ' Populate the contained TextBox with the values
         ' in the stringsValue array.
         Dim sb As New StringBuilder(Me.stringsValue.Length)

         Dim i As Integer
         For i = 0 To (Me.stringsValue.Length) - 1
             sb.Append(Me.stringsValue(i))
             sb.Append(ControlChars.Cr + ControlChars.Lf)
         Next i

         Me.textBox1.Text = sb.ToString()
     End Set
 End Property

// When the DesignerSerializationVisibility attribute has
// a value of "Content" or "Visible" the designer will 
// serialize the property. This property can also be edited 
// at design time with a CollectionEditor.
[DesignerSerializationVisibility( 
    DesignerSerializationVisibility.Content )]
public String[] Strings
{
    get
    {
        return this.stringsValue;
    }
    set
    {
        this.stringsValue = value;

        // Populate the contained TextBox with the values
        // in the stringsValue array.
        StringBuilder sb = 
            new StringBuilder(this.stringsValue.Length);

        for (int i = 0; i < this.stringsValue.Length; i++)
        {
            sb.Append(this.stringsValue[i]);
            sb.Append("\r\n");
        }

        this.textBox1.Text = sb.ToString();
    }
}

    // When the DesignerSerializationVisibility attribute has
    // a value of "Content" or "Visible" the designer will 
    // serialize the property. This property can also be edited 
    // at design time with a CollectionEditor.
public:
    [DesignerSerializationVisibility(
        DesignerSerializationVisibility::Content)]
    property array<String^>^ Strings
    {
        array<String^>^ get()
        {
            return this->stringsValue;
        }
        void set(array<String^>^ value)
        {
            this->stringsValue = value;

            // Populate the contained TextBox with the values
            // in the stringsValue array.
            StringBuilder^ sb =
                gcnew StringBuilder(this->stringsValue->Length);

            for (int i = 0; i < this->stringsValue->Length; i++)
            {
                sb->Append(this->stringsValue[i]);
                sb->Append(Environment::NewLine);
            }

            this->demoControlTextBox->Text = sb->ToString();
        }
    }

1. Drücken Sie F5, um das Projekt zu erstellen und das Steuerelement im UserControl-Testcontainer auszuführen.

2. Suchen Sie die Strings-Eigenschaft im PropertyGrid UserControl-Testcontainer. Klicken Sie auf die Strings-Eigenschaft und anschließend auf die Schaltfläche mit den Auslassungszeichen (), um den Zeichenfolgen-Editor zu öffnen.

3. Geben Sie mehrere Zeichenfolgen in den Zeichenfolgen-Editor ein. Trennen Sie sie, indem Sie am Ende jeder Zeichenfolge die EINGABETASTE drücken. Klicken Sie auf OK, wenn Sie alle Zeichenfolgen eingegeben haben.

Serialisieren einer Auflistungseigenschaft

Um das Serialisierungsverhalten des Steuerelements zu testen, fügen Sie es auf einem Formular ein und ändern den Inhalt der Auflistung mit dem Auflistungs-Editor. Sie können den Zustand der serialisierten Auflistung anhand einer speziellen Designer-Datei erkennen, in die der Windows Forms-Designer Code ausgibt.

So serialisieren Sie eine Auflistung

1. Fügen Sie der Projektmappe ein neues Windows-Anwendungsprojekt hinzu. Geben Sie dem Projekt die Bezeichnung SerializationDemoControlTest.

2. Suchen Sie in der Toolbox die Registerkarte mit dem Namen SerializationDemoControlLib Components. Auf dieser Registerkarte befindet sich das SerializationDemoControl. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Automatisches Füllen der Toolbox mit benutzerdefinierten Komponenten.

3. Fügen Sie ein SerializationDemoControl auf dem Formular ein.

4. Suchen Sie die Strings-Eigenschaft im Eigenschaftenfenster. Klicken Sie auf die Strings-Eigenschaft und anschließend auf die Schaltfläche mit den Auslassungszeichen (), um den Zeichenfolgen-Editor zu öffnen.

5. Geben Sie mehrere Zeichenfolgen in den Zeichenfolgen-Editor ein. Trennen Sie sie, indem Sie am Ende jeder Zeichenfolge die EINGABETASTE drücken. Klicken Sie auf OK, wenn Sie alle Zeichenfolgen eingegeben haben.

1. Klicken Sie im Projektmappen-Explorer auf die Schaltfläche Alle Dateien anzeigen.

2. Öffnen Sie den Knoten Form1. Darunter befindet sich eine Datei mit dem Namen Form1.Designer.cs oder Form1.Designer.vb. Dies ist die Datei, in die der Windows Forms-Designer Code ausgibt, der den Zustand des Formulars und dessen untergeordneten Steuerelemente zur Entwurfszeit wiedergibt. Öffnen Sie diese Datei im Code-Editor.

3. Öffnen Sie den Bereich Vom Windows Form-Designer generierter Code, und suchen Sie den Abschnitt serializationDemoControl1. Unter dieser Bezeichnung befindet sich der Code, der dem serialisierten Zustand des Steuerelements entspricht. Die Zeichenfolgen, die Sie in Schritt 5 eingegeben haben, werden in einer Zuweisung zur Strings-Eigenschaft angezeigt. Der Code im folgenden Beispiel entspricht in etwa dem Code, der angezeigt würde, wenn Sie die Zeichenfolgen "red", "orange" und "yellow" eingegeben hätten.

4. [Visual Basic]

   Me.serializationDemoControl1.Strings = New String() {"red", "orange", "yellow"}
   

5. [C#]

   this.serializationDemoControl1.Strings = new string[] {
           "red",
           "orange",
           "yellow"};
   

6. Ändern Sie im Code-Editor in der Strings-Eigenschaft den Wert von DesignerSerializationVisibilityAttribute auf Hidden.

7. [Visual Basic]

   <DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)> _
   

8. [C#]

   [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
   

9. Erstellen Sie die Projektmappe neu, und wiederholen Sie die Schritte 4 bis 8.

Nächste Schritte

Nachdem Sie wissen, wie Sie eine Auflistung von Standardtypen serialisieren können, sollten Sie es in Erwägung ziehen, Ihre benutzerdefinierten Steuerelemente stärker in die Entwurfszeitumgebung zu integrieren. In den folgenden Themen wird beschrieben, wie Sie die Entwurfszeitintegrierung der benutzerdefinierten Steuerelemente verbessern können:

• Architektur der Entwurfszeit

• Attribute in Windows Forms-Steuerelementen

• Übersicht über die Designerserialisierung

• Exemplarische Vorgehensweise: Erstellen eines Windows Forms-Steuerelements, das Visual Studio-Entwurfszeitfeatures nutzt

Siehe auch

Aufgaben

Gewusst wie: Serialisieren von Auflistungen der Standardtypen mit dem DesignerSerializationVisibilityAttribute

Exemplarische Vorgehensweise: Automatisches Füllen der Toolbox mit benutzerdefinierten Komponenten

Referenz

DesignerSerializationVisibilityAttribute

Konzepte

Übersicht über die Designerserialisierung