存取伺服器文件中的資料

發行項
08/12/2011

您可以對文件層級自訂中的資料進行程式設計，而不需使用 Microsoft Office Word 或 Microsoft Office Excel 的物件模型。這表示您可以在未安裝 Word 或 Excel 的伺服器存取文件中內含的資料。例如，伺服器上的程式碼 (例如，在 ASP.NET 頁面中) 可以自訂文件中的資料，並將自訂的文件傳送給使用者。當使用者開啟文件時，方案組件中的資料繫結 (Data Binding) 程式碼會將自訂的資料繫結至文件。這是因為文件中的資料與使用者介面分離的結果。如需詳細資訊，請參閱文件層級自訂中的快取資料。

**適用於：**本主題中的資訊適用於下列應用程式的文件層級專案：Excel 2007 和 Excel 2010、Word 2007 和 Word 2010。如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

快取在伺服器上使用的資料

若要快取文件中的資料物件，請在設計階段使用 CachedAttribute 屬性加以標示，或在執行階段使用主項目的 StartCaching 方法。在文件中快取資料物件時，Visual Studio Tools for Office Runtime 會將物件序列化至儲存在文件中的 XML 字串。要快取的物件必須符合特定需求。如需詳細資訊，請參閱快取資料。

伺服器端程式碼可以操作資料快取中的任何資料物件。繫結至快取資料執行個體的控制項會與使用者介面進行同步處理，因此對資料所做的任何伺服器端變更，會在文件於用戶端開啟時自動顯示。

存取快取中的資料

您可以從 Office 以外的應用程式存取快取中的資料，例如，從主控台應用程式、Windows Form 應用程式或 Web 網頁。存取快取資料的應用程式必須具有完全信任的權限，具有部分信任的 Web 應用程式無法插入、擷取或變更在 Office 文件中快取的資料。

資料快取可透過 ServerDocument 類別之 CachedData 屬性所公開 (Expose) 的集合階層架構存取：

CachedData 屬性 (Property) 會傳回 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 中之資料的程式碼範例，請參閱 HOW TO：從伺服器的活頁簿中擷取快取資料。

修改快取中的資料

若要修改快取資料物件，通常可以執行下列步驟：

將快取物件的 XML 表示還原序列化為物件的新執行個體。您可以使用表示快取資料物件之 CachedDataItem 的 Xml 屬性來存取 XML。
對此複本進行變更。
使用下列其中一個選項，將已變更的物件序列化為資料快取：
- 若要自動序列化變更，請使用 SerializeDataInstance 方法。這個方法會使用 DiffGram 格式，以便序列化資料快取中的 DataSet、DataTable 和具型別資料集物件。 DiffGram 格式會確保對離線文件之資料快取所進行的變更會正確地傳送至伺服器。如需詳細資訊，請參閱 DiffGrams (ADO.NET)。
- 如果要執行自己所偏好的序列化，將變更修改到快取的資料，您可以直接寫入至 Xml 屬性。如果您使用 DataAdapter 將 DataSet、DataTable 或具型別資料集中的資料變更更新至資料庫，請指定 DiffGram 格式。否則，DataAdapter 將會以加入新資料列而非修改現有資料列的方式更新資料庫。

如需示範如何直接寫入 Xml 屬性以將變更序列化至快取資料物件的程式碼範例，請參閱 HOW TO：變更伺服器活頁簿中的快取資料。

修改資料但不還原序列化目前的値

在某些情況下，您可能不先還原序列化快取物件目前的値，就要修改其値。例如，您要變更簡單型別物件的値 (例如字串或整數)，或是您要初始化伺服器上文件中快取的 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 的程式碼範例，請參閱 HOW TO：將資料插入伺服器上的活頁簿中。

修改資料快取中的 Null 值

當儲存並關閉文件時，資料快取不會儲存具有 null 值的物件。當您修改快取資料時，這個限制會造成下列數個結果：

如果您將資料快取中的任何物件設定為 null 値，當開啟文件時，資料快取中的所有物件都會自動設定為 null，而且當儲存並關閉文件時，整個資料快取都會遭到清除。也就是說，所有快取物件都會從資料快取中移除，而且 CachedData 集合將是空集合。
如果您使用資料快取中的 null 物件來建置方案時，而且要在第一次開啟文件之前使用 ServerDocument 類別來初始化這些物件，則必須確定您會初始化資料快取中的所有物件。如果只初始化部分物件，當開啟文件時，所有物件都會自動設定為 null，而且當儲存並關閉文件時，整個資料快取都會遭到清除。

存取快取中的具型別資料集

如果您想要同時從 Office 方案和 Office 以外的應用程式 (例如 Windows Form 應用程式或 ASP.NET 專案) 存取具型別資料集中的資料，則必須在兩個專案中參考的另一個組件中定義具型別資料集。如果您使用 [資料來源組態精靈] 或 [DataSet 設計工具] 將具型別資料集加入至每個專案，.NET Framework 就會將兩個專案內的具型別資料集視為不同的型別。如需建立具型別資料集的詳細資訊，請參閱 HOW TO：建立具型別資料集。