Tutorial: Enlazar controles de contenido a elementos XML personalizados

Este tutorial muestra cómo enlazar controles de contenido en una personalización de nivel de documento para Word a datos XML que se almacenan en el documento.

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

Word permite almacenar datos XML, denominados elementos XML personalizados, en un documento. Puede controlar la visualización de estos datos enlazando controles de contenido a los elementos de un elemento XML personalizado. El documento de ejemplo de este tutorial muestra información de empleado que se almacena en un elemento XML personalizado. Cuando abre el documento, los controles de contenido muestran los valores de los elementos XML. Cualquier cambio que realice en el texto de los controles de contenido se guardará en el elemento XML personalizado.

En este tutorial se muestran las tareas siguientes:

• Agregar controles de contenido al documento Word en un proyecto de nivel de 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 el esquema XML al documento en tiempo de diseño.

• Agregar el contenido del archivo XML a un elemento XML personalizado en el documento en tiempo de ejecución.

• Enlazar los controles de contenido a elementos del elemento XML personalizado.

• Enlazar un DropDownListContentControl a un conjunto de valores que se definen en el esquema XML.

  Nota:

  Es posible que tu equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las siguientes instrucciones. 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 Personalizar el IDE.

Requisitos previos

Necesitará los componentes siguientes para completar este tutorial:

• Una edición de Visual Studio que incluye las herramientas para desarrolladores de Microsoft Office. Para obtener más información, vea Configurar un equipo para desarrollar soluciones de Office.

• Microsoft Word.

Crear un nuevo proyecto de documento de Word

Crear un documento de Word que utilizará en el tutorial.

Para crear un nuevo proyecto de documento de Word

1. Cree un proyecto de documento de Word con el nombre EmployeeControls. Cree 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 a 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

1. En el documento de Word hospedado en el diseñador de Visual Studio, en la cinta de opciones, elija la pestaña Insertar .

2. En el grupo Tablas , elija Tabla e inserte una tabla con 2 columnas y 3 filas.

3. Escriba texto en la primera columna de modo que se parezca a la siguiente columna:

   Nombre del empleado
   Fecha de contratación
   Título

4. En la segunda columna de la tabla, elija la primera fila (junto a Nombre del empleado).

5. En la cinta de opciones, elija la pestaña Programador .

   Nota:

   Si la pestaña Desarrollador no está visible, primero debe mostrarla. Para obtener más información, vea Cómo: Mostrar la pestaña programador en la cinta de opciones.

6. En el grupo Controles, elija el botón Texto para agregar un PlainTextContentControl elemento a la primera celda.

7. En la segunda columna de la tabla, elija la segunda fila (junto a Fecha de contratación).

8. En el grupo Controles, elija el botón Selector de fechas para agregar un DatePickerContentControl elemento a la segunda celda.

9. En la segunda columna de la tabla, elija la tercera fila (junto a Título).

10. En el grupo Controles, elija el botón Lista desplegable para agregar un DropDownListContentControl elemento a la última celda.

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

Creación del archivo de datos XML

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

Para crear el archivo de datos

1. En el menú Proyecto , elija Agregar nuevo elemento.

   Aparecerá el cuadro de diálogo Agregar nuevo elemento.

2. En el panel Plantillas , seleccione Archivo XML.

3. Asigne al archivo el nombre employees.xml y elija el botón Agregar .

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

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

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

5. En Explorador de soluciones, elija el archivo employees.xml.

6. En la ventana Propiedades , seleccione la propiedad Acción de compilación y, a continuación, cambie el valor a Recurso incrustado.

   Este paso incrusta el archivo XML como un recurso en el ensamblado al compilar el proyecto. Esto le permite acceder al contenido del archivo XML en tiempo de ejecución.

Creación de un esquema XML

Si desea enlazar un control de contenido a un único elemento en un elemento XML personalizado, no es necesario utilizar un esquema XML. Sin embargo, para enlazar el 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 posibles valores para el elemento title. Enlazará el DropDownListContentControl a este elemento más adelante en este tutorial.

Para crear un esquema XML

1. En el menú Proyecto , elija Agregar nuevo elemento.

   Aparecerá el cuadro de diálogo Agregar nuevo elemento.

2. En el panel Plantillas , seleccione Esquema XML.

3. Asigne al esquema el nombre employees.xsd y elija el botón Agregar .

   Se abrirá el diseñador de esquemas.

4. En Explorador de soluciones, abra el menú contextual de employees.xsd y elija Ver código.

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

   <?xml version="1.0" encoding="utf-8" ?>
   <xs:schema xmlns="http://schemas.microsoft.com/vsto/samples"
       targetNamespace="http://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>
   

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

Adjuntar el esquema XML al documento

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

Para adjuntar el esquema XML al documento ( Word 2013 )

1. Active EmployeeControls.docx en el diseñador.

2. En la cinta de opciones, elija la pestaña Programador y, a continuación, elija el botón Complementos .

3. En el cuadro de diálogo Plantillas y complementos , elija la pestaña Esquema XML y, a continuación, elija el botón Agregar esquema .

4. Vaya al esquema employees.xsd que creó anteriormente, que se encuentra en el directorio del proyecto y, a continuación, elija el botón Abrir .

5. Elija el botón Aceptar en el cuadro de diálogo Esquema Configuración.

6. Elija el botón Aceptar para cerrar el cuadro de diálogo Plantillas y complementos .

Para asociar el esquema XML al documento (Word 2010)

1. Active EmployeeControls.docx en el diseñador.

2. En la cinta de opciones, elija la pestaña Programador .

3. En el grupo XML , elija el botón Esquema .

4. En el cuadro de diálogo Plantillas y complementos , elija la pestaña Esquema XML y, a continuación, elija el botón Agregar esquema .

5. Vaya al esquema employees.xsd que creó anteriormente, que se encuentra en el directorio del proyecto y elija el botón Abrir .

6. Elija el botón Aceptar en el cuadro de diálogo Esquema Configuración.

7. Elija el botón Aceptar para cerrar el cuadro de diálogo Plantillas y complementos .

   Se abre el panel de tareas Estructura XML.

8. 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 en el archivo XML, debe agregar el contenido del archivo XML a un nuevo elemento XML personalizado en el documento.

Para agregar un elemento XML personalizado al documento

1. En Explorador de soluciones, abra el menú contextual de ThisDocument.cs o ThisDocument.vb y, a continuación, elija Ver código.

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

   C#

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

   VB

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

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

   C#

   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;
   }
   

   VB

   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
   

4. Agregue el siguiente método 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 asegurarse de que el elemento XML personalizado solo se cree una vez, el método crea el elemento XML personalizado únicamente si en el documento no existe un elemento XML personalizado con un GUID coincidente. La primera vez que se llama a este método, guarda el valor de la propiedad Id a la cadena employeeXMLPartID. El valor de la cadena employeeXMLPartID se conserva en el documento porque se declaró mediante el atributo CachedAttribute.

   C#

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

   VB

   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", _
                   "http://schemas.microsoft.com/vsto/samples")
               employeeXMLPartID = employeeXMLPart.Id
           End If
       End If
   End Sub
   

Enlace de los controles de contenido a elementos del elemento XML personalizado

Enlace cada control de contenido a un elemento del elemento XML personalizado mediante la propiedad XMLMapping de cada control de contenido.

Para enlazar los controles de contenido a elementos en el elemento XML personalizado

1. Agrega el método siguiente a la clase ThisDocument: Este método enlaza cada control de contenido a un elemento en el elemento XML personalizado y establece el formato de visualización de fecha de la DatePickerContentControl.

   C#

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

   VB

   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
   

Ejecutar el código cuando se abre el documento

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

Para ejecutar el código cuando se abra el documento

1. Agregue el siguiente código 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 un nuevo elemento XML personalizado del documento y enlaza los controles de contenido a elementos del elemento XML personalizado.

   C#

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

   VB

   Dim xmlData As String = GetXmlFromResource()
   If xmlData IsNot Nothing Then
       AddCustomXmlPart(xmlData)
       BindControlsToCustomXmlPart()
   End If
   

Prueba del proyecto

Cuando abre el documento, los controles de contenido muestran datos de los elementos en el elemento XML personalizado. Puede hacer clic en DropDownListContentControl para seleccionar uno de los tres valores válidos del title elemento, que se definen en el archivo employees.xsd . Si modifica los datos en cualquiera de los controles de contenido, los nuevos valores se guardan en el elemento XML personalizado en el documento.

Para probar los controles de contenido

1. Presione F5 para ejecutar el proyecto.

2. Compruebe que la tabla del documento se parece a la siguiente tabla. Cada una de las cadenas en la segunda columna se obtiene a partir de un elemento del elemento XML personalizado del documento.

   Columna	Value
   Nombre del empleado	Karina Leal
   Fecha de contratación	1 de abril de 1999
   Título	Encargado

3. Elija la celda situada a la derecha de la celda Nombre del empleado y escriba otro nombre.

4. Elija la celda situada a la derecha de la celda Fecha de contratación y seleccione una fecha diferente en el selector de fechas.

5. Elija la celda situada a la derecha de la celda Título y seleccione un nuevo elemento en la lista desplegable.

6. Guarde y cierre el documento.

7. En Explorador de archivos, abra la carpeta \bin\Debug en la ubicación del proyecto.

8. Abra el menú contextual de EmployeeControls.docx y elija Cambiar nombre.

9. Asigne al archivo el nombre EmployeeControls.docx.zip.

   El documento EmployeeControls.docx se guarda en formato Open XML. Al cambiar el nombre de este documento con la extensión de nombre de archivo .zip , puede examinar el contenido del documento. Para obtener más información sobre Open XML, vea el artículo técnico Introducción a los formatos de archivo Open XML de Office (2007).

10. Abra el archivo EmployeeControls.docx.zip .

11. Abra la carpeta customXml .

12. Abra el menú contextual de item2.xml y, a continuación, elija Abrir.

    Este archivo contiene el elemento XML personalizado que agregó al documento.

13. Compruebe que los elementos name, hireDate, y title contengan los nuevos valores que introdujo en los controles de contenido en el documento.

14. Cierre el archivo item2.xml .

Pasos siguientes

Puede aprender más sobre cómo usar controles de contenido en estos temas:

• Use todos los controles de contenido disponibles para crear una plantilla. Para obtener más información, vea Tutorial: Creación de una plantilla mediante controles de contenido.

• Modifique los datos de los elementos XML personalizados con el documento 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.

• Utilice los controles de contenido para proteger elementos de un documento. Para obtener más información, vea Cómo: Proteger partes de documentos mediante controles de contenido.

Contenido relacionado

• Automatizar Word mediante objetos extendidos
• Controles de contenido
• Cómo: Agregar controles de contenido a documentos de Word
• Protección de partes de documentos mediante controles de contenido
• Información general sobre los elementos host y los controles host
• Limitaciones mediante programación de elementos host y controles host
• Agregar controles a documentos de Office en tiempo de ejecución