How to: Cache Data for Use Offline or on a Server

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.

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.

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 Caching Data.

Note

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.

   <Microsoft.VisualStudio.Tools.Applications.Runtime.Cached()> _
   Public employeesDataSet As DataSet
   

   [Microsoft.VisualStudio.Tools.Applications.Runtime.Cached()]
   public DataSet employeesDataSet;
   

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 Visual Studio Tools for Office Projects.

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

See Also

Tasks

How to: Programmatically Cache a Data Source in an Office Document

How to: Programmatically Stop Caching a Data Source

How to: Cache Data in a Password-Protected Document

Concepts

Caching Data

Accessing Data in Documents on the Server

Other Resources

Saving Data

Concurrency Control in ADO.NET