Caching Data

Article
11/16/2012

Applies to
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type Document-level projects Microsoft Office version 2007 Microsoft Office system Microsoft Office 2003 For more information, see Features Available by Application and Project Type.

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Project type

Document-level projects

Microsoft Office version

2007 Microsoft Office system
Microsoft Office 2003

For more information, see Features Available by Application and Project Type.

You can cache data objects in a document-level customization so that the data can be accessed offline, or without opening Microsoft Office Word or Microsoft Office Excel. To cache an object, the object must have a data type that meets certain requirements. Many common data types in the .NET Framework meet these requirements, including String, DataSet, and DataTable.

There are two ways to add an object to the data cache:

To add an object to the data cache when the solution is built, apply the CachedAttribute attribute to the object declaration. For more information, see How to: Cache Data for Use Offline or on a Server.
To programmatically add an object to the data cache at run time, use the StartCaching method of a host item, such as the ThisDocument or ThisWorkbook classes. For more information, see How to: Programmatically Cache a Data Source in an Office Document.

After you add an object to the data cache, you can access and modify the cached data without starting Word or Excel. For more information, see Accessing Data in Documents on the Server.

Requirements for Data Objects to be Cached

If you want to cache instances of data types that you create, the data types must meet these requirements:

Be a read/write public field or property of a host item, such as the ThisDocument or ThisWorkbook classes.
Not be an indexer or other parameterized property.

In addition, the data object must be serializable by the XmlSerializer class, which means it must have these characteristics:

Be a public type.
Have a public constructor with no parameters.
Not execute code that requires additional security privileges.
Expose only read/write public properties (other properties will be ignored).
Not expose multi-dimensional arrays (nested arrays are accepted).
Not return interfaces from properties and fields.
Not implement IDictionary if a collection.

Cached Data Size Limits

There are some limits to the total amount of data you can add to the data cache in a document, and to the size of any individual object in the data cache. If you exceed these limits, the application might close unexpectedly when the data is saved to the data cache.

To avoid these limits, follow these guidelines:

Do not add any object larger than 10 MB to the data cache.
Do not add more than 100 MB of total data to the data cache in a single document.

These are approximate values. The exact limits depend on several factors, including the available RAM and the number of running processes.

Controlling the Behavior of Cached Objects

To gain more control over the behavior of a cached object, you can implement the ICachedType interface on the type of the cached object. For example, you can implement this interface if you want to control how the user is notified when the object has been changed. For code examples that demonstrate how to implement ICachedType, see the ControlCollection class in the following sample applications:

Persisting Changes to Cached Data in Password-Protected Documents

In document-level projects for Word 2007 and Excel 2007, if you cache data objects in a document that is protected with a password, changes to the cached data are not saved. Starting in Visual Studio 2008 Service Pack 1 (SP1), you can save changes to the cached data by overriding two methods. Override these methods to temporarily remove the protection when the document is saved, and then reapply the protection after the save operation is complete.

For more information, see How to: Cache Data in a Password-Protected Document.

Preventing Data Loss When Adding Null Values to the Data Cache

When you add objects to the data cache, all of the cached objects must be initialized to a non-null value before the document is saved and closed. If any cached object has a null value when the document is saved and closed, the Visual Studio Tools for Office runtime will automatically remove all of the cached objects from the data cache.

If you add an object with a null value to the data cache by using the CachedAttribute attribute at design time, you can use the ServerDocument class to initialize the cached data objects before the document is opened. This is useful if you want to initialize the cached data on a server without Word or Excel installed, before the document is opened by an end user. For more information, see Accessing Data in Documents on the Server.

How Cached Data Is Stored in the Document

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. The way that the XML string is stored in the document depends on the version of Microsoft Office your solution works with:

In customizations for Microsoft Office 2003, the Visual Studio Tools for Office runtime stores the XML string in the Runtime Storage Control. The Runtime Storage Control is an ActiveX control that is embedded in the document. For more information, see Runtime Storage Control Overview.
In customizations for the 2007 Microsoft Office system, the Visual Studio Tools for Office runtime stores the XML string in a custom XML part in the document. For more information, see Custom XML Parts Overview.

Change History

Date	History	Reason
July 2008	Added information about caching data in password-protected documents.	SP1 feature change.
February 2009	Added information about cached data size limits.	Information enhancement.