Accessing Data in Documents on the Server

Article
11/06/2012

You can program against the data in a document-level customization without having to use the object model of Microsoft Office Word or Microsoft Office Excel. This means that you can access data that is contained in a document on a server that does not have Word or Excel installed. For example, code on a server (for instance, in an ASP.NET page) can customize the data in a document and send the customized document to an end user. When the end user opens the document, data binding code in the solution assembly binds the customized data into the document. This is possible because the data in the document is separated from the user interface. For more information, see Cached Data in Document-Level Customizations.

Applies to: The information in this topic applies to document-level projects for the following applications: Excel 2013 and Excel 2010; Word 2013 and Word 2010. For more information, see Features Available by Office Application and Project Type.

Caching Data for Use on a Server

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.

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.

Accessing Data in the Cache

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

Modifying Data in the Cache

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

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.
Make the changes to this copy.
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.
- 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.

Modifying Data Without Deserializing the Current Value

In some cases, you might want to modify the value of the cached object without first deserializing the current value. For example, you can do this if you are changing the value of an object that has a simple type, such as a string or integer, or if you are initializing a cached DataSet in a document on a server. In these cases, you can use the SerializeDataInstance method without first deserializing the current value of the cached object.

The following code example demonstrates how to change the value of 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")

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

The data cache does not store objects that have the value null when the document is saved and closed. This limitation has several consequences when you modify cached data:

If you set any object in the data cache to the value null, all of the objects in the data cache will be automatically set to null when the document is opened, and the entire data cache will be cleared when the document is saved and closed. That is, all of the cached objects will be removed from the data cache, and the CachedData collection will be empty.
If you build a solution with null objects in the data cache and you want to initialize these objects by using the ServerDocument class before the document is opened for the first time, you must ensure that you initialize all of the objects in the data cache. If you initialize only some of the objects, all of the objects will be set to null when the document is opened, and the entire data cache will be cleared when the document is saved and closed.

Accessing Typed Datasets in the Cache

If you want to access the data in a typed dataset both from an Office solution and from an application outside of Office, such as a Windows Forms application or an ASP.NET project, 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.

Share via