逐步解說：序列化標準類型的集合

發行項
10/18/2023

您的自訂控制項有時會將集合公開為屬性。本逐步解說示範如何使用 DesignerSerializationVisibilityAttribute 類別來控制集合在設計階段序列化的方式。將 Content 值套用至集合屬性可確保屬性會序列化。

警告

此內容是針對 .NET Framework 所撰寫。如果您使用 .NET 6 或更新版本，請謹慎使用此內容。 Windows Forms 的設計工具系統已變更，而且請務必檢閱自 .NET Framework 以來的設計工具變更一文。

若要將本主題中的程式碼複製為單一清單，請參閱如何：使用 DesignerSerializationVisibilityAttribute 序列化標準類型的集合。

必要條件

若要完成這個逐步解說，您必須具有 Visual Studio。

建立具有可序列化集合的控制項

第一個步驟是建立具有可序列化集合做為屬性的控制項。您可以使用 [集合編輯器 ] 來編輯此集合 的內容，您可以從 [屬性 ] 視窗存取 。

在 Visual Studio 中，建立 Windows 控制項程式庫專案，並將其命名為 SerializationDemoControlLib 。
將 UserControl1 重新命名為 SerializationDemoControl。如需詳細資訊，請參閱重新命名程式碼符號重構。
在 [ 屬性] 視窗中，將屬性的值 Padding.All 設定為 10 。
將 TextBox 控制項放在中 SerializationDemoControl 。
選取 TextBox 控制項。在 [ 屬性] 視窗中，設定下列屬性。

屬性變更為

多行 true

碼頭 Fill

[ScrollBars] Vertical

ReadOnly true

屬性	變更為
多行	`true`
碼頭	Fill
[ScrollBars]	Vertical
ReadOnly	`true`

在程式碼編輯器中，宣告中名為 stringsValue 的 SerializationDemoControl 字串陣列欄位。

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

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

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

Strings定義上的 SerializationDemoControl 屬性。

注意

值 Content 是用來啟用集合的序列化。

    // 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();
        }
    }

// 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.
 <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

按 F5 以建置專案，並在 UserControl 測試容器中執行您的控制項。
在 UserControl 測試容器的中 PropertyGrid 尋找 Strings 屬性。選取 Strings 屬性，然後選取省略號（）按鈕以開啟 [字串集合編輯器 ]。
在 [字串集合編輯器 ] 中 輸入數個字串。按每個字串結尾的 Enter 鍵來分隔它們。當您完成輸入字串時，按一下 [ 確定 ]。

注意

您輸入的字串會出現在 TextBox 的中 SerializationDemoControl 。

序列化集合屬性

若要測試控制項的序列化行為，您會將它放在表單上，並使用 集合編輯器 變更集合的內容。您可以查看 Windows Forms 設計 工具發出程式碼的特殊設計工具檔案 ，以查看序列化集合狀態。

將 Windows 應用程式專案新增至方案。將專案命名為 SerializationDemoControlTest。
在 [ 工具箱 ] 中，尋找名為 SerializationDemoControlLib 元件的 索引標籤。在此索引標籤中，您會發現 SerializationDemoControl 。如需詳細資訊，請參閱逐步解說：自動將自訂元件填入工具箱。
將放在 SerializationDemoControl 表單上。
Strings在 [屬性] 視窗中尋找屬性 。 Strings按一下屬性，然後按一下省略號（）按鈕以開啟 [字串集合編輯器 ]。
在 [字串集合編輯器 ] 中 輸入數個字串。在每一個字串結尾按 Enter 鍵來分隔它們。當您完成輸入字串時，按一下 [ 確定 ]。

注意

您輸入的字串會出現在 TextBox 的中 SerializationDemoControl 。
在方案總管中，按一下 [顯示所有檔案] 按鈕。
開啟 Form1 節點。其下方是名為 Form1.Designer.cs 或 Form1.Designer.vb 的檔案。這是 Windows Forms 設計工具 發出程式碼的檔案 ，代表表單及其子控制項的設計階段狀態。在 [程式碼編輯器] 中開啟此檔案。
開啟稱為 Windows Form Designer 產生的程式碼 區域，並尋找標示為 serializationDemoControl1 的 區段。此標籤下方是代表控制項序列化狀態的程式碼。您在步驟 5 中輸入的字串會出現在屬性的指派中 Strings 。 C# 和 Visual Basic 中的下列程式碼範例會顯示類似您輸入字串「red」、「orange」和「yellow」的程式碼。
```
this.serializationDemoControl1.Strings = new string[] {
        "red",
        "orange",
        "yellow"};
```
```
Me.serializationDemoControl1.Strings = New String() {"red", "orange", "yellow"}
```

在程式碼編輯器中，將屬性上的 Strings 值 DesignerSerializationVisibilityAttribute 變更為 Hidden 。

[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]

<DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)> _

重建解決方案並重複步驟 3 和 4。

注意

在此情況下， Windows Forms 設計工具 不會對屬性發出任何指派 Strings 。

下一步

一旦您知道如何序列化標準類型的集合，請考慮更深入地將自訂控制項整合到設計階段環境中。下列主題說明如何增強自訂控制項的設計階段整合：

逐步解說：序列化標準類型的集合

必要條件

建立具有可序列化集合的控制項

序列化集合屬性

下一步

另請參閱

意見反應

其他資源