To cache a data object in a document, mark it with the CachedAttribute attribute at design time, or use the StartCaching method of a host item at run time. When you cache a data object in a document, the Visual Studio Tools for Office runtime serializes the object into an XML string that is stored in the document. Objects must meet certain requirements to be eligible for caching. For more information, see Caching Data Objects.

Server-side code can manipulate any data objects in the data cache. Controls that are bound to cached data instances are synchronized with the user interface, so that any server-side changes that are made to the data show up automatically when the document is opened on the client.

You can access data in the cache from applications outside of Office, for example from a console application, a Windows Forms application, or a Web page. The application that accesses the cached data must have full trust; a Web application that has partial trust cannot insert, retrieve, or change data that is cached in an Office document.

The data cache is accessible through a hierarchy of collections that are exposed by the CachedData property of the ServerDocument class:

• The CachedData property returns a Microsoft.VisualStudio.Tools.Applications..::.CachedData, which contains all of the cached data in a document-level customization.

• Each Microsoft.VisualStudio.Tools.Applications..::.CachedData contains one or more CachedDataHostItem objects. A CachedDataHostItem contains all of the cached data objects that are defined within a single class.

• Each CachedDataHostItem contains one or more CachedDataItem objects. A CachedDataItem represents a single cached data object.

The following code example demonstrates how to access a cached string in the Sheet1 class of an Excel workbook project. This example is part of a larger example that is provided for the ServerDocument..::.Save method.

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

For a code example that demonstrates how to access the data in a cached DataSet, see How to: Retrieve Cached Data from a Workbook on a Server.

Note:

The ServerDocument class and the cached data classes in the Microsoft.VisualStudio.Tools.Applications namespace can be used only with solutions for the 2007 Microsoft Office system. If you are working with solutions for Microsoft Office 2003, use the ServerDocument class and cached data classes in the Microsoft.VisualStudio.Tools.Applications.Runtime namespace. For more information, see Managing Documents on a Server by Using the ServerDocument Class.

To modify a cached data object, you typically perform the following steps:

1. Deserialize the XML representation of the cached object into a new instance of the object. You can access the XML by using the Xml property of the CachedDataItem that represents the cached data object.

2. Make the changes to this copy.

3. Serialize the changed object back into the data cache by using one of the following options:

   • If you want to automatically serialize the changes, use the SerializeDataInstance method. This method uses the DiffGram format for serializing DataSet, DataTable, and typed dataset objects in the data cache. The DiffGram format ensures that changes to the data cache in an offline document are sent to the server correctly. For more information, see DiffGrams (ADO.NET).

   • If you want to perform your own serialization for changes to cached data, you can write directly to the Xml property. Specify the DiffGram format if you use a DataAdapter to update a database with changes made to data in a DataSet, DataTable, or typed dataset. Otherwise, the DataAdapter will update the database by adding new rows instead of modifying existing rows.

For a code example that demonstrates how to serialize changes to a cached data object by writing directly to the Xml property, see How to: Change Cached Data in a Workbook on a Server.

Modifying Data Without Deserializing the Current Value

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

Modifying Null Values in the Data Cache

If you want to access the data in a typed dataset both from a Visual Studio Tools for Office solution and from an application outside of Office, such as a Windows Forms application or an ASP.NET project, keep the following considerations in mind:

• You must define the typed dataset in a separate assembly that is referenced in both projects. If you add the typed dataset to each project by using the Data Source Configuration Wizard or the Dataset Designer, the .NET Framework will treat the typed datasets in the two projects as different types. For more information about creating typed datasets, see How to: Create a Typed Dataset.

• You must grant appropriate trust in the security policy of each end user to the assembly that contains the typed dataset. For more information, see Security Requirements to Run Office Solutions (2003 System).

Concepts