Tutorial: Serializar colecciones de tipos estándar con DesignerSerializationVisibilityAttribute

  • Artículo

Los controles personalizados exponen en algunas ocasiones una colección como una propiedad. Este tutorial muestra cómo se utiliza la clase DesignerSerializationVisibilityAttribute para controlar cómo se serializa una colección en tiempo de diseño. La aplicación del valor Content a la propiedad de colección garantiza la serialización de la propiedad.

Para copiar el código de este tema como un listado sencillo, vea Cómo: Serializar colecciones de tipos estándar con DesignerSerializationVisibilityAttribute.

Nota

Los cuadros de diálogo y comandos de menú que se ven pueden diferir de los descritos en la Ayuda, en función de los valores de configuración o de edición activos. Para cambiar la configuración, elija la opción Importar y exportar configuraciones del menú Herramientas. Para obtener más información, vea Trabajar con valores de configuración.

Requisitos previos

Para poder completar este tutorial, necesitará:

  • Permisos suficientes para poder crear y ejecutar proyectos de aplicación de Windows Forms en el equipo donde esté instalado Visual Studio.

Crear un control que tenga una colección serializable

El primer paso es crear un control que tenga una colección serializable como propiedad. Puede modificar el contenido de esta colección utilizando el Editor de la colección, al que puede obtener acceso desde la ventana Propiedades.

Para crear un control con una colección serializable

  1. Cree un proyecto de Biblioteca de controles de Windows denominado SerializationDemoControlLib. Para obtener más información, vea Windows Control Library Template.

  2. Cambie el nombre de UserControl1 a SerializationDemoControl. Para obtener más información, vea How to: Rename Identifiers.

  3. En la ventana Propiedades, establezca el valor de la propiedad Padding.All en 10.

  4. Coloque un control TextBox en SerializationDemoControl.

  5. Seleccione el control TextBox. En la ventana Propiedades, defina las propiedades siguientes:

    Propiedad

    Cambie a

    Multiline

    true

    Dock

    Fill

    ScrollBars

    Vertical

    ReadOnly

    true

  6. En el Editor de código, declare un campo de matriz de cadenas denominado stringsValue en 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. Defina la propiedad Strings en SerializationDemoControl.

Nota

El valor Content se utiliza para habilitar la serialización de la colección.

' 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. Presione F5 para generar el proyecto y ejecutar el control en el UserControl Test Container.

  2. Busque la propiedad Strings en PropertyGrid de UserControl Test Container. Haga clic en la propiedad Strings y, a continuación, haga clic en el botón de puntos suspensivos (Captura de pantalla de VisualStudioEllipsesButton) para abrir el Editor de colección de cadenas.

  3. Escriba varias cadenas en el Editor de colección de cadenas. Sepárelas presionando la tecla INTRO al final de cada cadena. Haga clic en Aceptar cuando termine de escribir las cadenas.

Nota

   Las cadenas que escriba aparecerán en el control TextBox de SerializationDemoControl.

Serializar una propiedad de colección

Para probar el comportamiento de serialización del control, colóquelo en un formulario y cambie el contenido de la colección con el Editor de la colección. Puede ver el estado de la colección serializada mirando un archivo de diseñador especial, en el que el Diseñador de Windows Forms emite código.

Para serializar una colección

  1. Agregue un proyecto de aplicación para Windows a la solución. Asigne al proyecto el nombre SerializationDemoControlTest.

  2. En el Cuadro de herramientas, busque la ficha denominada Componentes SerializationDemoControlLib. En esta ficha, encontrará el SerializationDemoControl. Para obtener más información, vea Tutorial: Rellenar automáticamente el cuadro de herramientas con componentes personalizados.

  3. Coloque un SerializationDemoControl en el formulario.

  4. Busque la propiedad Strings en la ventana Propiedades. Haga clic en la propiedad Strings y, a continuación, haga clic en el botón de puntos suspensivos (Captura de pantalla de VisualStudioEllipsesButton) para abrir el Editor de colección de cadenas.

  5. Escriba varias cadenas en el Editor de colección de cadenas. Sepárelas presionando la tecla INTRO al final de cada cadena. Haga clic en Aceptar cuando termine de escribir las cadenas.

Nota

Las cadenas que escriba aparecerán en el control TextBox de SerializationDemoControl.

  1. En el Explorador de soluciones, haga clic en el botón Mostrar todos los archivos.

  2. Abra el nodo Form1. Debajo habrá un archivo denominado Form1.Designer.cs o Form1.Designer.vb. Éste es el archivo en el que el Diseñador de Windows Forms emite código, que representa el estado en tiempo de diseño del formulario y sus controles secundarios. Abra este archivo en el Editor de código.

  3. Abra la región denominada Código generado por el Diseñador de Windows Forms y busque la sección con la etiqueta serializationDemoControl1. Debajo de esta etiqueta está el código que representa el estado serializado del control. Las cadenas que escribió en el paso 5 aparecerán en una asignación a la propiedad Strings. En el ejemplo de código siguiente se muestra código similar al que verá si ha escrito las cadenas "red", "orange" y "yellow".

  4. [Visual Basic]

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

  5. [C#]

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

  6. En el Editor de código, cambie el valor de DesignerSerializationVisibilityAttribute en la propiedad Strings a Hidden.

  7. [Visual Basic]

    <DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)> _

  8. [C#]

    [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]

  9. Vuelva a generar la solución y repita los pasos 4 a 8.

Nota

En este caso, el Diseñador de Windows Forms no emite una asignación a la propiedad Strings.

Pasos siguientes

Una vez que ya sabe serializar una colección de tipos estándar, puede aprender a perfeccionar la forma de integrar los controles personalizados en tiempo de diseño. En los temas siguientes se describe cómo se puede mejorar la integración en tiempo de diseño de los controles personalizados.

Vea también

Tareas

Cómo: Serializar colecciones de tipos estándar con DesignerSerializationVisibilityAttribute

Tutorial: Rellenar automáticamente el cuadro de herramientas con componentes personalizados

Referencia

DesignerSerializationVisibilityAttribute

Conceptos

Información general sobre serialización de diseñadores