共用方式為


存取伺服器文件中的資料

您可以根據文件層級自訂中的資料進行程式設計,而無需使用 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 表示還原序列化為物件的新執行個體。 可以使用表示快取資料物件的 CachedDataItemXml 屬性來存取 XML。

  2. 變更此複本。

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

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

    • 如果您想對快取資料的變更執行自己的序列化,可以直接寫入 Xml 屬性。 如果您使用 DataAdapter 透過對 DataSetDataTable 或具類型資料集中的資料所做的變更來更新資料庫,請指定 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 中建立和設定資料集