Walkthrough: Serializing Collections of Standard Types with the DesignerSerializationVisibilityAttribute

Your custom controls will sometimes expose a collection as a property. This walkthrough demonstrates how to use the DesignerSerializationVisibilityAttribute class to control how a collection is serialized at design time. Applying the Content value to your collection property ensures that the property will be serialized.

To copy the code in this topic as a single listing, see How to: Serialize Collections of Standard Types with the DesignerSerializationVisibilityAttribute.

Prerequisites

In order to complete this walkthrough, you will need:

• Sufficient permissions to be able to create and run Windows Forms application projects on the computer where Visual Studio is installed.

Creating a Control That Has a Serializable Collection

The first step is to create a control that has a serializable collection as a property. You can edit the contents of this collection using the Collection Editor, which you can access from the Properties window.

To create a control with a serializable collection

1. Create a Windows Control Library project called SerializationDemoControlLib. For more information, see Windows Control Library Template.

2. Rename UserControl1 to SerializationDemoControl. For more information, see How to: Rename Identifiers.

3. In the Properties window, set the value of the Padding.All property to 10.

4. Place a TextBox control in the SerializationDemoControl.

5. Select the TextBox control. In the Properties window, set the following properties.

   Property	Change to
   Multiline	true
   Dock	Fill
   ScrollBars	Vertical
   ReadOnly	true

6. In the Code Editor, declare a string array field named stringsValue in 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. Define the Strings property on the 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. Press F5 to build the project and run your control in the UserControl Test Container.

2. Find the Strings property in the PropertyGrid of the UserControl Test Container. Click the Strings property, then click the ellipsis () button to open the String Collection Editor.

3. Enter several strings in the String Collection Editor. Separate them by pressing the ENTER key at the end of each string. Click OK when you are finished entering strings.

Serializing a Collection Property

To test the serialization behavior of your control, you will place it on a form and change the contents of the collection with the Collection Editor. You can see the serialized collection state by looking at a special designer file, into which the Windows Forms Designer emits code.

To serialize a collection

1. Add a Windows Application project to the solution. For more information, see Add New Project Dialog Box. Name the project SerializationDemoControlTest.

2. In the Toolbox, find the tab named SerializationDemoControlLib Components. In this tab, you will find the SerializationDemoControl. For more information, see Walkthrough: Automatically Populating the Toolbox with Custom Components.

3. Place a SerializationDemoControl on your form.

4. Find the Strings property in the Properties window. Click the Strings property, then click the ellipsis () button to open the String Collection Editor.

5. Type several strings in the String Collection Editor. Separate them by pressing the ENTER key at the end of each string. Click OK when you are finished entering strings.

1. In Solution Explorer, click the Show All Files button.

2. Open the Form1 node. Beneath it is a file called Form1.Designer.cs or Form1.Designer.vb. This is the file into which the Windows Forms Designer emits code representing the design-time state of your form and its child controls. Open this file in the Code Editor.

3. Open the region called Windows Form Designer generated code and find the section labeled serializationDemoControl1. Beneath this label is the code representing the serialized state of your control. The strings you typed in step 5 appear in an assignment to the Strings property. The following code example shows code similar to what you will see if you typed the strings "red", "orange", and "yellow".

4. [Visual Basic]

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

5. [C#]

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

6. In the Code Editor, change the value of the DesignerSerializationVisibilityAttribute on the Strings property to Hidden.

7. [Visual Basic]

   <DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)> _
   

8. [C#]

   [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
   

9. Rebuild the solution and repeat steps 4 through 8.

Next Steps

Once you know how to serialize a collection of standard types, consider integrating your custom controls more deeply into the design-time environment. The following topics describe how to enhance the design-time integration of your custom controls:

• Design-Time Architecture

• Attributes in Windows Forms Controls

• Designer Serialization Overview

• Walkthrough: Creating a Windows Forms Control That Takes Advantage of Visual Studio Design-Time Features

See Also

Tasks

How to: Serialize Collections of Standard Types with the DesignerSerializationVisibilityAttribute

Walkthrough: Automatically Populating the Toolbox with Custom Components

Concepts

Designer Serialization Overview

Reference

DesignerSerializationVisibilityAttribute