title | ms.date | dev_langs | helpviewer_keywords | ms.assetid | description | |||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Walkthrough: Serializing Collections of Standard Types with the DesignerSerializationVisibilityAttribute |
03/30/2017 |
|
|
020c9df4-fdc5-4dae-815a-963ecae5668c |
Learn how to use the DesignerSerializationVisibilityAttribute class to control how a collection is serialized at design time. |
Your custom controls will sometimes expose a collection as a property. This walkthrough demonstrates how to use the xref:System.ComponentModel.DesignerSerializationVisibilityAttribute class to control how a collection is serialized at design time. Applying the xref:System.ComponentModel.DesignerSerializationVisibilityAttribute.Content value to your collection property ensures that the property will be serialized.
[!INCLUDE visual-studio-designer-net]
To copy the code in this topic as a single listing, see How to: Serialize Collections of Standard Types with the DesignerSerializationVisibilityAttribute.
You need Visual Studio to complete this walkthrough.
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.
-
In Visual Studio, create a Windows Control Library project, and name it SerializationDemoControlLib.
-
Rename
UserControl1
toSerializationDemoControl
. For more information, see Rename a code symbol refactoring. -
In the Properties window, set the value of the xref:System.Windows.Forms.Padding.All%2A?displayProperty=nameWithType property to 10.
-
Place a xref:System.Windows.Forms.TextBox control in the
SerializationDemoControl
. -
Select the xref:System.Windows.Forms.TextBox control. In the Properties window, set the following properties.
Property Change to Multiline true
Dock xref:System.Windows.Forms.DockStyle.Fill ScrollBars xref:System.Windows.Forms.ScrollBars.Vertical ReadOnly true
-
In the Code Editor, declare a string array field named
stringsValue
inSerializationDemoControl
.[!code-cppSystem.ComponentModel.DesignerSerializationVisibilityAttribute#4] [!code-csharpSystem.ComponentModel.DesignerSerializationVisibilityAttribute#4] [!code-vbSystem.ComponentModel.DesignerSerializationVisibilityAttribute#4]
-
Define the
Strings
property on theSerializationDemoControl
.[!NOTE] The xref:System.ComponentModel.DesignerSerializationVisibilityAttribute.Content value is used to enable serialization of the collection.
[!code-cppSystem.ComponentModel.DesignerSerializationVisibilityAttribute#5] [!code-csharpSystem.ComponentModel.DesignerSerializationVisibilityAttribute#5] [!code-vbSystem.ComponentModel.DesignerSerializationVisibilityAttribute#5]
-
Press F5 to build the project and run your control in the UserControl Test Container.
-
Find the Strings property in the xref:System.Windows.Forms.PropertyGrid of the UserControl Test Container. Select the Strings property, then select the ellipsis (
) button to open the String Collection Editor.
-
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.
Note
The strings you typed appear in the xref:System.Windows.Forms.TextBox of the SerializationDemoControl
.
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.
-
Add a Windows Application project to the solution. Name the project
SerializationDemoControlTest
. -
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. -
Place a
SerializationDemoControl
on your form. -
Find the
Strings
property in the Properties window. Click theStrings
property, then click the ellipsis () button to open the String Collection Editor.
-
Type several strings in the String Collection Editor. Separate them by pressing Enter at the end of each string. Click OK when you are finished entering strings.
[!NOTE] The strings you typed appear in the xref:System.Windows.Forms.TextBox of the
SerializationDemoControl
. -
In Solution Explorer, click the Show All Files button.
-
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.
-
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 examples in C# and Visual Basic, show code similar to what you will see if you typed the strings "red", "orange", and "yellow".this.serializationDemoControl1.Strings = new string[] { "red", "orange", "yellow"};
Me.serializationDemoControl1.Strings = New String() {"red", "orange", "yellow"}
-
In the Code Editor, change the value of the xref:System.ComponentModel.DesignerSerializationVisibilityAttribute on the
Strings
property to xref:System.ComponentModel.DesignerSerializationVisibility.Hidden.[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
<DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)> _
-
Rebuild the solution and repeat steps 3 and 4.
Note
In this case, the Windows Forms Designer emits no assignment to the Strings
property.
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:
- xref:System.ComponentModel.DesignerSerializationVisibilityAttribute
- Walkthrough: Automatically Populating the Toolbox with Custom Components