Cached data in document-level customizations

Applies to: Visual Studio Visual Studio for Mac

A primary goal of document-level customizations is to separate data from view in Office documents. Data refers to the information that is stored in the document, including numbers and text. View refers to the user interface and the object model of Microsoft Office Word and Microsoft Office Excel.

Visual Studio separates the data from the view in document-level customizations by enabling data to be embedded as a data island, also called the data cache. You can read or modify the data directly without starting Word or Excel. This is useful when you need to modify data in documents on a server that does not have Microsoft Office installed. Word and Excel are intended for use in client environments; they are not designed to be run 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.

For more information about document-level customizations, see Office solutions development overview (VSTO) and Architecture of document-level customizations.

Understand the cached data programming model

The data island can contain any object in your solution that meets certain requirements. These objects include DataSet objects, DataTable objects, and any other object that can be serialized by the XmlSerializer class. For more information, see Cache data.

To provide the view for the cached data, you can bind Windows Forms controls and host controls on the document to objects in the data island. Data binding between the data island and the data-bound controls keeps the two synchronized. You can also add validation code to the data that is independent of the controls. For more information, see Bind data to controls in Office solutions.

Host controls are extended versions of native objects in the Excel and Word object models. Unlike the native objects, host controls can be bound directly to managed data objects. For more information, see Host items and host controls overview and Windows Forms controls on Office documents overview.

Access cached data on the server

To access cached data in a document, you can use the ServerDocument class. This class is part of the Visual Studio Tools for Office runtime, and it can be used on a server without running Excel or Word. When the user opens the document after you modify the cached data, any controls that are bound to the data are automatically synchronized to the changes, and the user is presented with the updated data. For more information, see Access data in documents on the server.

Excel and Word are not needed to write to the data on the server, only to view it on the client. Excel and Word do not even need to be installed on the server. This provides improved scalability and the ability to perform fast batch processing of documents that contain data islands.

Data caching for offline use

Storing data in the data island enables offline scenarios. When a user first opens a document or requests the document from the server, the data island is filled with the most recent data. The data island is cached in the document and is then available offline. The user (and your code) can manipulate the data, even though no live connection is available. When the user reconnects, the changes to the data can be propagated back to a server data source.

Cached data and custom XML parts compared

Custom XML parts were introduced in the 2007 Microsoft Office system as a way to store arbitrary pieces of XML in a document. Although custom XML parts are useful in many of the same scenarios as the data cache, there are some differences between the data island and custom XML parts. For more information about custom XML parts, see Custom XML parts overview.

The following table lists some of the differences and similarities.

See also

• Data in Office solutions
• Architecture of Office solutions in Visual Studio