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. For more information, see DiffGrams (ADO.NET).
-
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.
For a code example that demonstrates how to serialize changes to a cached data object by writing directly to the Xml property, see How to: Change Cached Data in a Workbook on a Server.
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();
}
For a code example that demonstrates how to initialize a cached DataSet on a server, see How to: Insert Data into a Workbook on a Server.
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.