CachedDataItem.SerializeDataInstance(Object) Method

Definition

Namespace:

Microsoft.VisualStudio.Tools.Applications

Assembly:

Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll

Serializes data to the cached data object that is represented by the CachedDataItem.

public:
 void SerializeDataInstance(System::Object ^ value);

public void SerializeDataInstance (object value);

member this.SerializeDataInstance : obj -> unit

Public Sub SerializeDataInstance (value As Object)

Parameters

value

Object

The object that contains the data you want to save to an object in the data cache.

Examples

The following code example uses the SerializeDataInstance method to modify the value of a string that is cached in a worksheet of an Excel workbook.

This example requires:

• A document-level customization for Excel that has a Sheet1 class in the ExcelWorkbook1 namespace, and a cached string in the Sheet1 class named CachedString.

• A console application project or some other non-Office project.

• References to the following assemblies:

  • Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll

  • Microsoft.VisualStudio.Tools.Applications.Runtime.dll

• Imports (for Visual Basic) or using (for C#) statements for Microsoft.VisualStudio.Tools.Applications and Microsoft.VisualStudio.Tools.Applications.Runtime namespaces at the top of your code file.

private void ModifyCachedString(string documentPath)
{
    int runtimeVersion = 0;
    ServerDocument serverDocument1 = null;

    try
    {
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);

        if (runtimeVersion != 3)
        {
            MessageBox.Show("This document does not have a Visual Studio Tools for " +
                "Office customization, or it has a customization that was created with " +
                "a version of the runtime that is incompatible with this version of the " +
                "ServerDocument class.");
            return;
        }

        if (ServerDocument.IsCacheEnabled(documentPath))
        {
            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();
            }
        }
        else
        {
            MessageBox.Show("The specified document does not have cached data.");
        }
    }
    catch (System.IO.FileNotFoundException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.");
    }
    catch (UnknownCustomizationFileException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document has a file " +
            "extension that is not supported by Visual Studio Tools for Office.");
    }
    finally
    {
        if (serverDocument1 != null)
            serverDocument1.Close();
    }
}

Private Sub ModifyCachedString(ByVal documentPath As String)
    Dim runtimeVersion As Integer = 0
    Dim serverDocument1 As ServerDocument = Nothing

    Try
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath)
        If runtimeVersion <> 3 Then
            MessageBox.Show("This document does not have a Visual Studio Tools for Office " & _
                "customization, or it has a customization that was created with a version of " & _
                "the runtime that is incompatible with this version of the ServerDocument class.")
            Return
        End If

        If ServerDocument.IsCacheEnabled(documentPath) Then
            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
        Else
            MessageBox.Show("The specified document does not have cached data.")
        End If

    Catch ex As System.IO.FileNotFoundException
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.")
    Catch ex As UnknownCustomizationFileException
        System.Windows.Forms.MessageBox.Show("The specified document has a file " & _
            "extension that is not supported by Visual Studio Tools for Office.")
    Finally
        If Not (serverDocument1 Is Nothing) Then
            serverDocument1.Close()
        End If
    End Try
End Sub

Remarks

Use the SerializeDataInstance method to initialize or modify the value of a cached data object. This method serializes the value parameter into the cached data object that the CachedDataItem represents. To make changes to specific data values in a complex cached data object, such as a DataSet or DataTable, deserialize the XML representation of the cached data into a new instance of the cached object, make the changes to this copy, and then use the SerializeDataInstance method to serialize the changes back into the data cache. For more information, see Accessing Data in Documents on the Server and Walkthrough: Changing Cached Data in a Workbook on a Server.

This method uses the DiffGram format for serializing DataSet, DataTable, and typed dataset objects into the data cache. This ensures that changes to the data cache in an offline document are sent to the server correctly.