How to: Cache data for use offline or on a server

You can mark a data item to be cached in the document, so that it is available offline. This also makes it possible for the data in the document to be manipulated by other code when the document is stored on a server.

Applies to: The information in this topic applies to document-level projects for Excel and Word. For more information, see Features available by Office application and project type.

You can mark a data item to be cached when the data item is declared in your code, or, if you are using a DataSet, by setting a property in the Properties window. If you are caching a data item that is not a DataSet or DataTable, ensure that it meets the criteria for being cached in the document. For more information, see Cache data.


Datasets created using Visual Basic that are marked as Cached and WithEvents (including datasets that are dragged from the Data Sources window or Toolbox that have the CacheInDocument property set to True) have an underscore prefixed to their names in the cache. For example, if you create a dataset and name it Customers, the CachedDataItem name will be _Customers in the cache. When you use ServerDocument to access this cached item, you must specify _Customers instead of Customers.

To cache data in the document using code

  1. Declare a public field or property for the data item as a member of a host item class in your project, such as the ThisDocument class in a Word project or the ThisWorkbook class in an Excel project.

  2. Apply the CachedAttribute attribute to the member to mark the data item to be stored in the document's data cache. The following example applies this attribute to a field declaration for a DataSet.

    public DataSet employeesDataSet;
    <Microsoft.VisualStudio.Tools.Applications.Runtime.Cached()> _
    Public employeesDataSet As DataSet
  3. Add code to create an instance of the data item and, if applicable, to load it from the database.

    The data item is only loaded when it is first created; thereafter, the cache stays with the document and you must write other code to update it.

To cache a dataset in the document by using the Properties window

  1. Add the dataset to the project by using tools in the Visual Studio designer, for example, by adding a data source to your project using the Data Sources window.

  2. Create an instance of the dataset if you do not already have one, and select the instance in the designer.

  3. In the Properties window, set the CacheInDocument property to True.

    For more information, see Properties in Office Projects.

  4. In the Properties window, set the Modifiers property to Public (by default it is Internal).

See also