访问服务器上的文档数据

更新：2007 年 11 月

适用对象
本主题中的信息仅适用于指定的 Visual Studio Tools for Office 项目和 Microsoft Office 版本。 项目类型 文档级项目 Microsoft Office 版本 2007 Microsoft Office system Microsoft Office 2003 有关更多信息，请参见按应用程序和项目类型提供的功能。

利用 Visual Studio Tools for Office，您可以依据文档级自定义项中的数据进行编程，而不必使用 Microsoft Office Word 或 Microsoft Office Excel 的对象模型。这意味着，您可以在未安装 Word 或 Excel 的服务器上访问包含在文档中的数据。例如，服务器上的代码（例如，在 ASP.NET 页中）可以自定义文档中的数据，并将自定义文档发送给最终用户。当最终用户打开文档时，解决方案程序集中的数据绑定代码便会将自定义数据绑定到文档中。这种做法之所以可行，是因为文档中的数据与用户界面是分离的。有关更多信息，请参见 文档级自定义项中的数据模型。

缓存数据以便在服务器上使用

若要在文档中缓存数据对象，请在设计时使用 CachedAttribute 属性标记该数据对象，或在运行时使用宿主项的 StartCaching 方法。当您将数据对象缓存在文档中时，Visual Studio Tools for Office 运行时会将该对象序列化为存储在文档中的一个 XML 字符串。对象必须符合一定的条件才能进行缓存。有关更多信息，请参见 缓存数据。

服务器端的代码可操作数据缓存中的任何数据对象。绑定到已缓存的数据实例的控件与用户界面同步，因此，当在客户端打开文档时，在服务器端对数据所做的任何更改都会自动出现。

访问缓存中的数据

可以从 Office 之外的应用程序访问缓存中的数据，例如，从控制台应用程序、Windows 窗体应用程序或网页进行访问。访问缓存数据的应用程序必须具备完全信任；具备部分信任的 Web 应用程序不能插入、检索或更改 Office 文档中缓存的数据。

数据缓存可通过由 ServerDocument 类的 CachedData 属性所公开的集合的层次结构进行访问：

• CachedData 属性返回 Microsoft.VisualStudio.Tools.Applications.CachedData，它包含文档级自定义项中的所有缓存数据。

• 每个 Microsoft.VisualStudio.Tools.Applications.CachedData 包含一个或多个 CachedDataHostItem 对象。CachedDataHostItem 包含单个类中定义的所有缓存数据对象。

• 每个 CachedDataHostItem 包含一个或多个 CachedDataItem 对象。CachedDataItem 表示单个缓存数据对象。

下面的代码示例演示如何访问在 Excel 工作簿项目的 Sheet1 类中缓存的字符串。此示例摘自一个为 ServerDocument.Save 方法提供的更大的示例。

serverDocument1 = New ServerDocument(documentPath)
Dim hostItem1 As CachedDataHostItem = _
    serverDocument1.CachedData.HostItems("ExcelWorkbook1.Sheet1")
Dim dataItem1 As CachedDataItem = hostItem1.CachedData("CachedString")

serverDocument1 = new ServerDocument(documentPath);
CachedDataHostItem hostItem1 = 
    serverDocument1.CachedData.HostItems["ExcelWorkbook1.Sheet1"];
CachedDataItem dataItem1 = hostItem1.CachedData["CachedString"];

有关演示如何访问缓存的 DataSet 中的数据的代码示例，请参见如何：从服务器上的工作簿中检索缓存的数据。

说明：
ServerDocument 类和 Microsoft.VisualStudio.Tools.Applications 命名空间中的缓存数据类只能与 2007 Microsoft Office system 解决方案一起使用。如果正在处理 Microsoft Office 2003 解决方案，请使用 ServerDocument 类和 Microsoft.VisualStudio.Tools.Applications.Runtime 命名空间中的缓存数据类。有关更多信息，请参见使用 ServerDocument 类管理服务器上的文档。

修改缓存中的数据

若要修改缓存数据对象，通常可执行下列操作：

1. 将缓存对象的 XML 表示形式反序列化为该对象的一个新实例。通过使用表示该缓存数据对象的 CachedDataItem 的 Xml 属性，可以访问与之相应的 XML。

2. 对此副本进行更改。

3. 使用下列选项之一，将更改后的对象重新序列化到数据缓存中：

   • 如果要自动序列化所做的更改，请使用 SerializeDataInstance 方法。此方法使用 DiffGram 格式将 DataSet、DataTable 和类型化数据集对象序列化为数据缓存。DiffGram 格式确保将对脱机文档中的数据缓存更改正确发送到服务器。有关更多信息，请参见 DiffGram (ADO.NET)。

   • 如果想要对缓存数据更改执行自己的序列化，可直接写入 Xml 属性。如果使用 DataAdapter 更新对 DataSet、DataTable 或类型化数据集中的数据进行了更改的数据库，请指定 DiffGram 格式。否则，DataAdapter 将通过添加新行而不是修改现有行的方式来更新数据库。

有关演示如何通过直接写入 Xml 属性来序列化对缓存数据对象的更改的代码示例，请参见 如何：更改服务器上的工作簿中的缓存数据。

在不反序列化当前值的情况下修改数据

在某些情况下，可能需要直接修改缓存对象的值，而不是先对当前值进行反序列化。例如，如果要更改具有简单类型（例如，字符串型或整型）的对象的值，或在服务器上初始化文档中缓存的 DataSet，就可以这样做。在这些情况下，可以直接使用 SerializeDataInstance 方法，而不用先反序列化缓存对象的当前值。

下面的代码示例演示如何更改在 Excel 工作簿项目的 Sheet1 类中缓存的字符串的值。此示例摘自一个为 ServerDocument.Save 方法提供的更大的示例。

serverDocument1 = New ServerDocument(documentPath)
Dim hostItem1 As CachedDataHostItem = _
    serverDocument1.CachedData.HostItems("ExcelWorkbook1.Sheet1")
Dim dataItem1 As CachedDataItem = hostItem1.CachedData("CachedString")

If dataItem1 IsNot Nothing AndAlso _
    Type.GetType(dataItem1.DataType).Equals(GetType(String)) Then

    dataItem1.SerializeDataInstance("This is the new cached string value.")
    serverDocument1.Save()
End If

serverDocument1 = new ServerDocument(documentPath);
CachedDataHostItem hostItem1 = 
    serverDocument1.CachedData.HostItems["ExcelWorkbook1.Sheet1"];
CachedDataItem dataItem1 = hostItem1.CachedData["CachedString"];

if (dataItem1 != null &&
    Type.GetType(dataItem1.DataType) == typeof(string))
{
    dataItem1.SerializeDataInstance("This is the new cached string value.");
    serverDocument1.Save();
}

有关演示如何在服务器上初始化缓存的 DataSet 的代码示例，请参见如何：向服务器上的工作簿中插入数据。

修改数据缓存中的 Null 值

在保存和关闭文档时，数据缓存不会存储值为 null 的对象。此限制会对缓存数据的修改产生下列影响：

• 在将数据缓存中的任意对象设置为 null 值后，数据缓存中的所有对象都将在文档打开时自动设置为 null，这样在保存和关闭文档时将清除整个数据缓存。换言之，数据缓存中的所有缓存对象都将被移除，且 CachedData 集合将变为空。

• 如果生成的解决方案在数据缓存中含有 null 对象，并且您希望在首次打开文档之前使用 ServerDocument 类初始化这些对象，则必须确保初始化该数据缓存中的所有对象。如果只初始化其中的部分对象，则在打开文档时，所有对象都将设置为 null，这样在保存和关闭文档时将清除整个数据缓存。

访问缓存中的类型化数据集

如果要访问来自 Visual Studio Tools for Office 解决方案和 Office 之外的应用程序（如 Windows 窗体应用程序或 Visual Studio Tools for Office 项目）的类型化数据集中的数据，请考虑下面的注意事项：

• 必须在两个项目中均引用的单独的程序集中定义类型化程序集。如果使用“数据源配置向导”或“数据集设计器”向每个项目添加类型化数据集，则 .NET Framework 将这两个项目中的类型化程序集视为不同的类型。有关创建类型化数据集的更多信息，请参见如何：创建类型化数据集。

• 必须在最终用户的安全策略中为包含类型化数据集的程序集授予合适的信任级别。有关更多信息，请参见 运行 Office 解决方案的安全要求 (2003 System)。

请参见

任务

如何：从服务器上的工作簿中检索缓存的数据

如何：更改服务器上的工作簿中的缓存数据

如何：向服务器上的工作簿中插入数据

概念

访问服务器上的文档数据

文档级自定义项中的数据模型

DiffGram (ADO.NET)