演练：将内容控件绑定到自定义 XML 部件

项目
02/24/2013

本演练演示如何将 Word 文档级自定义项中的内容控件绑定到存储在文档中的 XML 数据。

**适用于：**本主题中的信息适用于 Word 2013 和 Word 2010 的文档级项目。有关更多信息，请参见按 Office 应用程序和项目类型提供的功能。

Word 允许您将 XML 数据（称为“自定义 XML 部件”）存储在文档中。可以通过将内容控件绑定到自定义 XML 部件中的元素来控制此数据的显示。此演练中的示例文档显示存储于自定义 XML 部件中的雇员信息。当您打开文档时，内容控件将显示 XML 元素的值。对内容控件中的文本所做的任何更改都保存在自定义 XML 部件中。

本演练阐释了以下任务：

在文档级项目中，在设计时向 Word 文档中添加内容控件。
创建一个 XML 数据文件和一个 XML 架构，该架构定义要绑定到内容控件的元素。
在设计时将 XML 架构附加到文档。
在运行时将 XML 文件的内容添加到文档中的自定义 XML 部件。
将内容控件绑定到自定义 XML 部件中的元素。
将 DropDownListContentControl 绑定到 XML 架构中定义的值集。

说明
对于在以下说明中使用的某些 Visual Studio 用户界面元素，您的计算机可能会显示不同的名称或位置。这些元素取决于您所使用的 Visual Studio 版本和您所使用的设置。有关更多信息，请参见 Visual Studio 设置。

系统必备

您需要以下组件来完成本演练：

Visual Studio 2012 的一个版本，其中包含 Microsoft Office 开发工具。有关更多信息，请参见[将计算机配置为开发 Office 解决方案](bb398242\(v=vs.110\).md)。

Word 2013 或 Word 2010。

链接到视频有关本主题的视频版本，请参见 Video How to: Binding Content Controls to Custom XML Parts（视频帮助：将内容控件绑定到自定义 XML 部件）。

创建新的 Word 文档项目

创建将在演练中使用的 Word 文档。

创建新的 Word 文档项目

创建一个名为 EmployeeControls 的 Word 文档项目。为解决方案创建一个新文档。有关更多信息，请参见如何：在 Visual Studio 中创建 Office 项目。

Visual Studio 将在设计器中打开新的 Word 文档，并将 EmployeeControls 项目添加到**“解决方案资源管理器”**。

将内容控件添加到文档

创建一个包含三种不同类型内容控件的表，用户可在这些控件中查看或编辑有关雇员的信息。

将内容控件添加到文档

在承载于 Visual Studio 设计器中的 Word 文档中，单击功能区上的**“插入”**选项卡。
在**“表”组中，单击“表”**，并插入一个包含二列三行的表。
在第一列中键入文本，以使该列与下面的列相似：

雇员姓名

雇佣日期

标题
在该表的第二列中，单击第一行（**“雇员姓名”**旁边）。
在功能区上，单击**“开发人员”**选项卡。

说明

如果看不到“开发人员”选项卡，您必须首先显示该选项卡。有关更多信息，请参见如何：在功能区上显示“开发人员”选项卡。
在**“控件”组中，单击“文本”**按钮，将 PlainTextContentControl 添加到第一个单元格中。
在该表的第二列中，单击第二行（**“雇佣日期”**旁边）。
在**“控件”组中，单击“日期选择器”**按钮，将 DatePickerContentControl 添加到第二个单元格中。
在该表的第二列中，单击第三行（**“职称”**旁边）。
在**“控件”组中，单击“下拉列表”**按钮，以将 DropDownListContentControl 添加到最后一个单元格。

说明
如果看不到“开发人员”选项卡，您必须首先显示该选项卡。有关更多信息，请参见如何：在功能区上显示“开发人员”选项卡。

这就是此项目的整个用户界面。如果现在运行项目，您可以在第一行中键入文本，并在第二行中选择一个日期。下一步是在 XML 文件中将要显示的数据附加到文档。

创建 XML 数据文件

通常，您将从外部源（如文件或数据库）获取要存储在自定义 XML 部件中的 XML 数据。在本演练中，您将创建一个包含雇员数据的 XML 文件，并用那些将绑定到文档中的内容控件的元素对该文件进行标记。为了使数据在运行时可用，请将该 XML 文件作为一项资源嵌入到自定义项程序集内。

创建数据文件

在**“项目”菜单上，单击“添加新项”**。

将显示**“添加新项”**对话框。
在**“模板”窗格中选择“XML 文件”**。
将该文件命名为 employees.xml，然后单击**“添加”**。

employees.xml 文件将在代码编辑器中打开。

将 employees.xml 文件的内容替换为以下文本。

<?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>

在**“解决方案资源管理器”**中，单击 employees.xml。
在**“属性”窗口中，选择“生成操作”属性，然后将值更改为“嵌入的资源”**。

通过进行此步骤，当您生成项目时，即会将 XML 文件以资源的形式嵌入在程序集中。这样，您将能够在运行时访问 XML 文件的内容。

创建 XML 架构

如果要将内容控件绑定到自定义 XML 部件中的单一元素，您不必使用 XML 架构。但是，若要将 DropDownListContentControl 绑定到一组值，则必须创建可对之前创建的 XML 数据文件进行验证的 XML 架构。XML 架构定义 title 元素的可能值。在此演练的后面，会将 DropDownListContentControl 绑定到此元素。

创建 XML 架构

在**“项目”菜单上，单击“添加新项”**。

将显示**“添加新项”**对话框。
在**“模板”窗格中选择“XML 架构”**。
将架构命名为 employees.xsd，然后单击**“添加”**。

架构设计器将打开。
在**“解决方案资源管理器”中右击 employees.xsd，然后单击“查看代码”**。

将 employees.xsd 文件的内容替换为以下架构。

<?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>

在**“文件”菜单上，单击“全部保存”**以保存对 employees.xml 和 employees.xsd 文件所做的更改。

将 XML 架构附加到文档

必须将 XML 架构附加到文档，才能将 DropDownListContentControl 绑定到 title 元素的有效值。

将 XML 架构附加到文档

在设计器中激活**“EmployeeControls.docx”**。
在功能区上，单击**“开发人员”**选项卡。
在**“XML”组中，单击“架构”**。
在**“模板和加载项”对话框中单击“XML 架构”选项卡，然后单击“添加架构”**。
浏览到之前创建的 employees.xsd 架构（位于项目目录中），然后单击**“打开”**。
在**“架构设置”对话框中单击“确定”**。
单击**“确定”以关闭“模板和加载项”**对话框。

随即打开**“XML 结构”**任务窗格。
关闭**“XML 结构”**任务窗格。

将自定义 XML 部件添加到文档

必须将 XML 文件的内容添加到文档中新的自定义 XML 部件，然后才能将内容控件绑定到 XML 文件中的元素。

将自定义 XML 部件添加到文档

在**“解决方案资源管理器”中右击 ThisDocument.cs 或 ThisDocument.vb，然后单击“查看代码”**。

将以下声明添加到 ThisDocument 类。此代码声明将用于向文档中添加自定义 XML 部件的一些对象。

<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'";

将下面的方法添加到 ThisDocument 类中。此方法获取以资源形式嵌入在程序集中的 XML 数据文件的内容，并以 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;
}

将下面的方法添加到 ThisDocument 类中。AddCustomXmlPart 方法创建一个新的自定义 XML 部件，其中包含传递到该方法的 XML 字符串。

为了确保只创建一次自定义 XML 部件，该方法只有在具有匹配 GUID 的自定义 XML 部件在文档中不存在时才会创建自定义 XML 部件。第一次调用此方法时，它会将 Id 属性的值保存到 employeeXMLPartID 字符串。employeeXMLPartID 字符串的值保留在文档中，因为它是通过使用 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);
            employeeXMLPart.NamespaceManager.AddNamespace("ns", 
                @"https://schemas.microsoft.com/vsto/samples");
            employeeXMLPartID = employeeXMLPart.Id;
        }
    }
}

将内容控件绑定到自定义 XML 部件中的元素

使用各个内容控件的 XMLMapping 属性将各个内容控件绑定到自定义 XML 部件中的元素。

将内容控件绑定到自定义 XML 部件中的元素

将下面的方法添加到 ThisDocument 类中。此方法将各个内容控件绑定到自定义 XML 部件中的元素，并设置 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);
}

在文档打开时运行代码

在文档打开时创建自定义 XML 部件并将自定义控件绑定到数据。

在文档打开时运行代码

将以下代码添加到 ThisDocument 类的 ThisDocument_Startup 方法。此代码从 employees.xml 文件中获取 XML 字符串，将 XML 字符串添加到文档中新的自定义 XML 部件，并将内容控件绑定到自定义 XML 部件中的元素。

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

string xmlData = GetXmlFromResource();

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

测试项目

当您打开文档时，内容控件将显示自定义 XML 部件的元素中的数据。您可以单击 DropDownListContentControl 以选择 title 元素的三个有效值之一，这些值是在 employees.xsd 文件中定义的。如果在任何内容控件中编辑数据，新值将保存在文档内的自定义 XML 部件中。

测试内容控件

按 F5 运行项目。
验证文档中的表是否类似于下表。第二列中的每个字符串都是从文档内自定义 XML 部件的元素中获取的。

雇员姓名

Karina Leal

雇佣日期

April 1, 1999

标题

经理
在“雇员姓名”单元格右边的单元格中单击，并键入其他姓名。
在“雇佣日期”单元格右边的单元格中单击，并在日期选择器中选择其他日期。
在“职称”单元格右边的单元格中单击，并从下拉列表中选择一个新项。
保存并关闭该文档。
在文件资源管理器中，打开\ bin \ debug 文件夹在项目的位置下。
右击 EmployeeControls.docx，然后单击**“重命名”**。
将文件命名为“EmployeeControls.docx.zip”。

“EmployeeControls.docx”文档是以 Open XML 格式保存的。通过用 .zip 文件扩展名重命名此文档，您可以检查文档的内容。有关 Open XML 的更多信息，请参见技术文章介绍 Office (2007) Open XML 文件格式。
双击 EmployeeControls.docx.zip 文件。
双击 customXml 文件夹。
右击 item2.xml，然后单击**“打开”**。

此文件包含您添加到文档的自定义 XML 部件。
验证 name、hireDate 和 title 元素是否包含您在文档的内容控件中输入的新值。
关闭 item2.xml 文件。