存取伺服器文件中的資料

  • 發行項

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

適用對象：本主題資訊適用於 Excel 及 Word 的文件層級專案。 如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

快取資料供於伺服器上使用

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

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

存取快取中的資料

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

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

  • CachedData 屬性會傳回 CachedData，其中包含文件層級自訂中的所有快取資料。

  • 每個 CachedData 包含一個或多個 CachedDataHostItem 物件。 CachedDataHostItem 包含單一類別內定義的所有快取資料物件。

  • 每個 CachedDataHostItem 包含一個或多個 CachedDataItem 物件。 CachedDataItem 表示單一快取的資料物件。

    下列程式碼範例示範如何在 Excel 活頁簿專案的 Sheet1 類別中存取快取的字串。 這個範例是 Save 方法提供的大型範例的一部分。

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

修改快取中的資料

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

  1. 將快取物件的 XML 表示還原序列化為物件的新執行個體。 可以使用表示快取資料物件的 CachedDataItem 的 Xml 屬性來存取 XML。

  2. 變更此複本。

  3. 使用下列其中一個選項，將已變更的物件序列化回資料快取：

    • 如果您想要自動序列化變更，請使用 SerializeDataInstance 方法。 這個方法會使用 DiffGram 格式，在資料快取中序列化 DataSet、DataTable 和具類型的資料集物件。 DiffGram 格式可確保離線文件中資料快取的變更正確傳送到伺服器。

    • 如果您想對快取資料的變更執行自己的序列化，可以直接寫入 Xml 屬性。 如果您使用 DataAdapter 透過對 DataSet、DataTable 或具類型資料集中的資料所做的變更來更新資料庫，請指定 DiffGram 格式。 否則，DataAdapter 會藉由新增新的資料列來更新資料庫，而不是修改現有的資料列。

修改資料而不還原序列化目前的值

在某些情況下，您可能想要修改快取物件的值，而不需要先還原序列化目前的值。 例如，如果您要變更具有簡單類型的物件值 (例如：字串或整數)，或是正在初始化伺服器上文件中快取的 DataSet，則可以執行此動作。 在這些情況下，您可以使用 SerializeDataInstance 方法，而不需要先還原序列化快取物件的目前值。

下列程式碼範例示範如何在 Excel 活頁簿專案的 Sheet1 類別中變更快取的值。 這個範例是 Save 方法提供的大型範例的一部分。

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

修改資料快取中的 null 值

儲存並關閉文件時，資料快取不會儲存值為 null 的物件。 當您修改快取的資料時，這項限制會產生幾個後果：

  • 如果您將資料快取中的任何物件設定為 null 值，則開啟文件時，資料快取中的所有物件都會自動設定為 null，而且儲存和關閉文件時，將會清除整個資料快取。 也就是說，所有快取的物件都會從資料快取中移除，而且 CachedData 集合會是空的。

  • 如果建立的解決方案在資料快取中包含 null 物件，並且希望在首次開啟文件之前使用 ServerDocument 類別初始化這些物件，則必須確保已初始化資料快取中的所有物件。 如果只初始化部分物件，則開啟文件時所有物件都會設定為 null，而且儲存和關閉檔時會清除整個資料快取。

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

如果想要從 Office 解決方案和 Office 外部的應用程式存取具類型資料集中的資料 (例如：Windows Forms 應用程式或 ASP.NET 專案)，則必須在兩個專案參考的個別組件中定義具類型資料集。 如果使用 [資料來源組態] 精靈或 [DataSet 設計工具] 將具類型的資料集新增至每個專案，.NET Framework 會將這兩個專案中的具類型資料集視為不同類型的資料集。 如需建立具類型資料集的詳細資訊，請參閱在 Visual Studio 中建立和設定資料集。

相關內容