Tutorial: Enlazar controles de contenido a elementos XML personalizados

Artículo
08/10/2011

En este tutorial se muestra cómo se enlazan los controles de contenido de una personalización de nivel de documento para Word a los datos XML almacenados en el documento.

Se aplica a: la información de este tema se aplica a los proyectos de nivel de documento para Word 2007 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Word permite almacenar datos XML, denominados elementos XML personalizados, en un documento. Es posible controlar la presentación de estos datos enlazando los controles de contenido con objetos de los elementos XML personalizados. En el documento de ejemplo de este tutorial se muestra información sobre los empleados que está guardada en un elemento XML personalizado. Al abrir el documento, los controles de contenido muestran los valores de los elementos XML. Todos los cambios que se realicen en el texto de los controles de contenido se guardarán en el elemento XML personalizado.

En este tutorial se muestran las tareas siguientes:

Agregar controles de contenido al documento de Word en un proyecto en el nivel del documento en tiempo de diseño.
Crear un archivo de datos XML y un esquema XML que defina los elementos que se van a enlazar a los controles de contenido.
Asociar en esquema XML al documento en tiempo de diseño.
Agregar el contenido del archivo XML a un elemento XML personalizado del documento en tiempo de ejecución.
Enlazar los controles de contenido a objetos del elemento XML personalizado.
Enlazar un objeto DropDownListContentControl a un conjunto de valores que se definen en el esquema XML.

Nota

Es posible que su equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio incluidos en las instrucciones siguientes. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos. Para obtener más información, vea Valores de configuración de Visual Studio.

Requisitos previos

Necesita los componentes siguientes para completar este tutorial:

Una edición de Visual Studio 2010 que incluye las herramientas para desarrolladores de Microsoft Office. Para obtener más información, vea [Configurar un equipo para desarrollar soluciones de Office](bb398242\(v=vs.100\).md).

Microsoft Office Word 2007 o Word 2010.

vínculo a vídeo Para obtener una versión en vídeo de este tema, vea Video How to: Binding Content Controls to Custom XML Parts.

Crear un nuevo proyecto de documento de Word

Cree el documento de Word que utilizará en el tutorial.

Para crear un nuevo proyecto de documento de Word

Cree un proyecto de documento de Word con el nombre EmployeeControls. Crear un nuevo documento para la solución. Para obtener más información, vea Cómo: Crear proyectos de Office en Visual Studio.

Visual Studio abre el nuevo documento de Word en el diseñador y agrega el proyecto EmployeeControls al Explorador de soluciones.

Agregar controles de contenido al documento

Cree una tabla que contenga tres tipos diferentes de controles de contenido donde el usuario pueda ver o modificar la información sobre un empleado.

Para agregar controles de contenido al documento

En el documento de Word que se hospeda en el diseñador de Visual Studio, en el cinta de opciones, haga clic en la ficha Insertar.
En el grupo Tablas, haga clic en Tabla e inserte una tabla con dos columnas y tres filas.
En la primera columna, escriba texto de modo que se asemeje a la columna siguiente:

Nombre del empleado

Fecha de contratación

Título
En la segunda columna de la tabla, haga clic en la primera fila (junto a Nombre del empleado).
En la cinta de opciones, haga clic en la ficha Desarrollador.

Nota

Si la ficha Desarrollador no está visible, debe mostrarla primero. Para obtener más información, consulte Cómo: Mostrar la pestaña Programador en la cinta de opciones.
En el grupo Controles, haga clic en el botón Texto para agregar un control PlainTextContentControl en la primera celda.
En la segunda columna de la tabla, haga clic en la segunda fila (junto a Fecha de contratación).
En el grupo Controles, haga clic en el botón Selector de fecha para agregar un control DatePickerContentControl a la segunda celda.
En la segunda columna de la tabla, haga clic en la tercera fila (junto a Puesto).
En el grupo Controles, haga clic en el botón Lista despegable para agregar un control DropDownListContentControl en la última celda.

Ésta es todas la interfaz de usuario de este proyecto. Si ejecuta el proyecto ahora, puede escribir texto en la primera fila y seleccionar una fecha en la segunda fila. El paso siguiente consiste en asociar los datos que desea mostrar con el documento en un archivo XML.

Crear el archivo de datos XML

Normalmente, obtendrá los datos XML para almacenar en un elemento XML personalizado de un origen externo, como un archivo o una base de datos. En este tutorial, creará un archivo XML con los datos de empleado marcados con los elementos que enlazará a los controles de contenido del documento. Para que los datos estén disponibles en tiempo de ejecución, incruste el archivo XML como un recurso en el ensamblado de personalización.

Para crear el archivo de datos

En el menú Proyecto, haga clic en Agregar nuevo elemento.

Aparecerá el cuadro de diálogo Agregar nuevo elemento.
En el panel Plantillas, seleccione Archivo XML.
Denomine el archivo employees.xml y, a continuación, haga clic en Agregar.

El archivo employees.xml se abre en el Editor de código.

Reemplace el contenido del archivo employees.xml por el siguiente texto.

<?xml version="1.0" encoding="utf-8" ?>
<employees xmlns="https://schemas.microsoft.com/vsto/samples">
  <employee>
    <name>Karina Leal</name>
    <hireDate>1999-04-01</hireDate>
    <title>Manager</title>
  </employee>
</employees>

En el Explorador de soluciones, haga clic en employees.xml.
En la ventana Propiedades, seleccione la propiedad Acción de compilación y, a continuación, cambie el valor a Recurso incrustado.

En este paso, el archivo XML se incrusta como recurso en el ensamblado cuando se genera el proyecto. De este modo, puede obtener acceso al archivo XML en tiempo de ejecución.

Crear un esquema XML

Si desea enlazar un control de contenido a un único objeto de un elemento XML personalizado, no es necesario utilizar un esquema XML. Sin embargo, para enlazar el control DropDownListContentControl a un conjunto de valores, debe crear un esquema XML que valide el archivo de datos XML que creó anteriormente. El esquema XML define los valores posibles del elemento title. Enlazará el control DropDownListContentControl a este elemento posteriormente en este tutorial.

Para crear un esquema XML

En el menú Proyecto, haga clic en Agregar nuevo elemento.

Aparecerá el cuadro de diálogo Agregar nuevo elemento.
En el panel Plantillas, seleccione Esquema XML.
Asigne al esquema el nombre employees.xsd y haga clic en Agregar.

Se abre el diseñador de esquemas.
En el Explorador de soluciones, haga clic con el botón secundario del mouse en employees.xsd y, a continuación, en Ver código.

Reemplace el contenido del archivo employees.xsd por el siguiente esquema.

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema xmlns="https://schemas.microsoft.com/vsto/samples" 
    targetNamespace="https://schemas.microsoft.com/vsto/samples"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified">
  <xs:element name="employees" type="EmployeesType"></xs:element>
  <xs:complexType name="EmployeesType">
    <xs:all>
      <xs:element name="employee" type="EmployeeType"/>
    </xs:all>
  </xs:complexType>
  <xs:complexType name="EmployeeType">
    <xs:sequence>
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
      <xs:element name="hireDate" type="xs:date" minOccurs="1" maxOccurs="1"/>
      <xs:element name="title" type="TitleType" minOccurs="1" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="TitleType">
    <xs:restriction base="xs:string">
      <xs:enumeration value ="Engineer"/>
      <xs:enumeration value ="Designer"/>
      <xs:enumeration value ="Manager"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

En el menú Archivo, haga clic en Guardar todo para guardar los cambios realizados en los archivos employees.xml y employees.xsd.

Asociar el esquema XML al documento

Debe asociar el esquema XML al documento para enlazar el control DropDownListContentControl a los valores válidos del elemento title.

Para asociar el esquema XML al documento

Active EmployeeControls.docx en el diseñador.
En la cinta de opciones, haga clic en la ficha Desarrollador.
En el grupo XML, haga clic en Esquema.
En el cuadro de diálogo Plantillas y complementos, haga clic en la ficha Esquema XML y, a continuación, haga clic en Agregar esquema.
Vaya al esquema employees.xsd que creó anteriormente y que se encuentra en el directorio del proyecto, y haga clic en Abrir.
Haga clic en Aceptar en el cuadro de diálogo Configuración del esquema.
Haga clic en Aceptar para cerrar el cuadro de diálogo Plantillas y complementos.

Se abre el panel de tareas Estructura XML.
Cierre el panel de tareas Estructura XML.

Agregar un elemento XML personalizado al documento

Antes de poder enlazar los controles de contenido a los elementos del archivo XML, debe agregar el contenido del archivo XML a un nuevo elemento XML personalizado del documento.

Para agregar un elemento XML personalizado al documento

En el Explorador de soluciones, haga clic con el botón secundario en ThisDocument.cs o ThisDocument.vb y, a continuación, haga clic en Ver código.

Agregue las declaraciones siguientes a la clase ThisDocument. Este código declara varios objetos que utilizará para agregar un elemento XML personalizado al documento.

<Cached()> _
Public employeeXMLPartID As String = String.Empty
Private employeeXMLPart As Office.CustomXMLPart
Private Const prefix As String = "xmlns:ns='https://schemas.microsoft.com/vsto/samples'"

[CachedAttribute()]
public string employeeXMLPartID = string.Empty;
private Office.CustomXMLPart employeeXMLPart;
private const string prefix = "xmlns:ns='https://schemas.microsoft.com/vsto/samples'";

Agregue el método siguiente a la clase ThisDocument. Este método obtiene el contenido del archivo de datos XML que se incrusta como recurso en el ensamblado y devuelve el contenido como una cadena XML.

Private Function GetXmlFromResource() As String
    Dim asm As System.Reflection.Assembly = _
        System.Reflection.Assembly.GetExecutingAssembly()
    Dim stream1 As System.IO.Stream = asm.GetManifestResourceStream( _
            "EmployeeControls.employees.xml")

    Using resourceReader As System.IO.StreamReader = _
        New System.IO.StreamReader(stream1)
        If resourceReader IsNot Nothing Then
            Return resourceReader.ReadToEnd()
        End If
    End Using

    Return Nothing
End Function

private string GetXmlFromResource()
{
    System.Reflection.Assembly asm =
        System.Reflection.Assembly.GetExecutingAssembly();
    System.IO.Stream stream1 = asm.GetManifestResourceStream(
        "EmployeeControls.employees.xml");

    using (System.IO.StreamReader resourceReader =
            new System.IO.StreamReader(stream1))
    {
        if (resourceReader != null)
        {
            return resourceReader.ReadToEnd();
        }
    }

    return null;
}

Agregue el método siguiente a la clase ThisDocument. El método AddCustomXmlPart crea un nuevo elemento XML personalizado que contiene una cadena XML que se pasa al método.

Para garantizar que el elemento XML personalizado sólo se crea una vez, el método únicamente crea el elemento XML personalizado si no existe en el documento ningún elemento XML personalizado con un GUID que coincida. La primera vez que se llama a este método, guarda el valor de la propiedad Id en la cadena employeeXMLPartID. El valor de la cadena employeeXMLPartID se conserva en el documento porque se declaró mediante el atributo CachedAttribute.

Private Sub AddCustomXmlPart(ByVal xmlData As String)
    If xmlData IsNot Nothing Then

        employeeXMLPart = Me.CustomXMLParts.SelectByID(employeeXMLPartID)
        If (employeeXMLPart Is Nothing) Then
            employeeXMLPart = Me.CustomXMLParts.Add(xmlData)
            employeeXMLPart.NamespaceManager.AddNamespace("ns", _
                "https://schemas.microsoft.com/vsto/samples")
            employeeXMLPartID = employeeXMLPart.Id
        End If
    End If
End Sub

private void AddCustomXmlPart(string xmlData)
{
    if (xmlData != null)
    {
        employeeXMLPart = this.CustomXMLParts.SelectByID(employeeXMLPartID);
        if (employeeXMLPart == null)
        {
            employeeXMLPart = this.CustomXMLParts.Add(xmlData, missing);
            employeeXMLPart.NamespaceManager.AddNamespace("ns", 
                @"https://schemas.microsoft.com/vsto/samples");
            employeeXMLPartID = employeeXMLPart.Id;
        }
    }
}

Enlazar controles de contenido a objetos del elemento XML personalizado

Para enlazar cada control de contenido a un objeto del elemento XML personalizado, utilice la propiedad XMLMapping de cada control de contenido.

Para enlazar los controles de contenido a objetos del elemento XML personalizado

Agregue el método siguiente a la clase ThisDocument. Este método enlaza cada control de contenido con un objeto del elemento XML personalizado y establece el formato de presentación de la fecha de DatePickerContentControl.

Private Sub BindControlsToCustomXmlPart()
    Dim xPathName As String = "ns:employees/ns:employee/ns:name"
    Me.PlainTextContentControl1.XMLMapping.SetMapping(xPathName, _
        prefix, employeeXMLPart)

    Dim xPathDate As String = "ns:employees/ns:employee/ns:hireDate"
    Me.DatePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy"
    Me.DatePickerContentControl1.XMLMapping.SetMapping(xPathDate, _
        prefix, employeeXMLPart)

    Dim xPathTitle As String = "ns:employees/ns:employee/ns:title"
    Me.DropDownListContentControl1.XMLMapping.SetMapping(xPathTitle, _
        prefix, employeeXMLPart)
End Sub

private void BindControlsToCustomXmlPart()
{
    string xPathName = "ns:employees/ns:employee/ns:name";
    this.plainTextContentControl1.XMLMapping.SetMapping(xPathName,
        prefix, employeeXMLPart);

    string xPathDate = "ns:employees/ns:employee/ns:hireDate";
    this.datePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy";
    this.datePickerContentControl1.XMLMapping.SetMapping(xPathDate,
        prefix, employeeXMLPart);

    string xPathTitle = "ns:employees/ns:employee/ns:title";
    this.dropDownListContentControl1.XMLMapping.SetMapping(xPathTitle,
        prefix, employeeXMLPart);
}

Ejecutar el código al abrir el documento

Cree el elemento XML personalizado y enlace los controles personalizados a los datos cuando se abra el documento.

Para ejecutar el código al abrir el documento

Agregue el código siguiente al método ThisDocument_Startup de la clase ThisDocument. Este código obtiene la cadena XML del archivo employees.xml, agrega la cadena XML a una nuevo elemento XML personalizado del documento y enlaza los controles de contenido a los objetos del elemento XML personalizado.
```
Dim xmlData As String = GetXmlFromResource()
If xmlData IsNot Nothing Then
    AddCustomXmlPart(xmlData)
    BindControlsToCustomXmlPart()
End If
```
```
string xmlData = GetXmlFromResource();

if (xmlData != null)
{
    AddCustomXmlPart(xmlData);
    BindControlsToCustomXmlPart();
}
```

Probar el proyecto

Al abrir el documento, los controles de contenido muestran los datos de los objetos del elemento XML personalizado. Puede hacer clic en el control DropDownListContentControl para seleccionar uno de los tres valores válidos del elemento title, que se definen en el archivo employees.xsd. Si modifica los datos de algún control de contenido, los nuevos valores se guardarán en el elemento XML personalizado del documento.

Para probar los controles de contenido

Presione F5 para ejecutar el proyecto.
Compruebe que la tabla del documento se parece a la tabla siguiente. Cada una de las cadenas de la segunda columna se obtiene de un objeto del elemento XML personalizado del documento.

Nombre del empleado

Karina Leal

Fecha de contratación

April 1, 1999

Título

Administrador
Haga clic en la celda situada a la derecha de la celda Nombre del empleado y escriba un nombre diferente.
Haga clic en la celda situada a la derecha de la celda Fecha de contratación y seleccione una fecha diferente en el selector de fecha.
Haga clic en la celda situada a la derecha de la celda Puesto y seleccione un nuevo elemento de la lista desplegable.
Guarde y cierre el documento.
En el Explorador de Windows, abra la carpeta \bin\Debug situada en la ubicación de su proyecto.
Haga clic con el botón secundario del mouse en EmployeeControls.docx y, a continuación, haga clic en Cambiar nombre.
Llame al archivo EmployeeControls.docx.zip.

El documento EmployeeControls.docx se guarda en el formato Open XML. Al cambiar el nombre de este documento por la extensión de nombre de archivo .zip, puede examinar el contenido del documento. Para obtener más información acerca del formato Open XML, vea el artículo técnico Introducing the Office (2007) Open XML File Formats.
Haga doble clic en el archivo EmployeeControls.docx.zip.
Haga doble clic en la carpeta customXml.
Haga clic con el botón secundario en item2.xml y, a continuación, haga clic en Abrir.

Este archivo contiene el elemento XML personalizado que agregó al documento.
Compruebe que los elementos name, hireDate y title contienen los nuevos valores que especificó en los controles de contenido del documento.
Cierre el archivo item2.xml.

Pasos siguientes

Puede obtener más información acerca de cómo se utilizan los controles de contenido en los temas siguientes:

Utilizar todos los controles de contenido disponibles para crear una plantilla. Para obtener más información, consulte Tutorial: Crear una plantilla mediante controles de contenido.
Modificar los datos de los elementos XML personalizados mientras el documento está cerrado. La próxima vez que el usuario abra el documento, los controles de contenido que están enlazados a los elementos XML mostrarán los nuevos datos. Para obtener más información, consulte Cómo: Agregar elementos XML personalizados a documentos sin iniciar Microsoft Office.
Utilizar controles de contenido para proteger elementos de un documento. Para obtener más información, consulte Cómo: Proteger elementos de documentos mediante controles de contenido.