Serializing the Workbook

Saving and Loading Workbooks

Workbooks can be serialized in byte sequences wrapped by .NET streams. Such streams may represent files, memory buffers, communication pipes, TCP sockets, and so on. In serialized form a workbook might be saved in a database record too. To save the current workbook into a stream, call the SaveToStream method, and respectively, to load a workbook from a stream, call LoadFromStream. Two shortcut methods are provided for work with files. SaveToFile creates a disk file and a stream that wraps it and invokes SaveToStream. LoadFromFile opens a read-stream on a disk file and invokes LoadFromStream.

Saving Attached Data

All objects referenced by the workbook, such as images and fonts, are serialized together with the workbook elements. The Tag objects that are associated with workbook elements are also saved if they are of value data type, if they are marked as [Serializable] or if their class implements the ISerializable interface. If a tag is not serializable it won't be saved by the Save* methods.

XML Serialization

It is possible to save a workbook as an XML document. To do that, call the SaveToXml method of the Workbook class. To deserialize a workbook back from its XML representation, call the LoadFromXml method. The control raises the SerializeTag and DeserializeTag events to enable serialization of complex Tag objects. The following code illustrates how to serialize and deserialize a custom worksheet tag:

C#

// The custom class that will be used as a tag
public class SampleData
{
    public string CategoryId
    {
        get;
        set;
    }

    public int OrderNumber
    {
        get;
        set;
    }
}

...

// The SerializeTag event handler
private void OnSerializeTag(object sender, SerializeTagEventArgs e)
{
    var sampleData = e.Tag as SampleData;
    var dataElement = e.Context.AddChildElement("Data", e.Representation);
    e.Context.WriteString(sampleData.CategoryId, "CategoryId", dataElement);
    e.Context.WriteInt(sampleData.OrderNumber, "OrderNumber", dataElement);
    e.Handled = true;
}

// The DeserializeTag event handler
private void OnDeserializeTag(object sender, SerializeTagEventArgs e)
{
    var dataElement = e.Representation.Element("Data");
    var categoryId = e.Context.ReadString("CategoryId", dataElement);
    var orderNumber = e.Context.ReadInt("OrderNumber", dataElement);
    e.Tag = new SampleData { CategoryId = categoryId, OrderNumber = orderNumber };
    e.Handled = true;
}

Visual Basic

' The custom class that will be used as a tag
Public Class SampleData

    Public Property CategoryId() As String
        Get
            Return _categoryId
        End Get
        Set(ByVal value As String)
            _categoryId = value
        End Set
    End Property

    Public Property OrderNumber() As Integer
        Get
            Return _orderNumber
        End Get
        Set(ByVal value As Integer)
            _orderNumber = value
        End Set
    End Property

    Private _categoryId As String
    Private _orderNumber As Integer

End Class

...

' The SerializeTag event handler
Private Sub OnSerializeTag(ByVal sender As Object, ByVal e As SerializeTagEventArgs)
    Dim sampleData = CType(e.Tag, SampleData)
    Dim dataElement = e.Context.AddChildElement("Data", e.Representation)
    e.Context.WriteString(sampleData.CategoryId, "CategoryId", dataElement)
    e.Context.WriteInt(sampleData.OrderNumber, "OrderNumber", dataElement)
    e.Handled = True
End Sub

' The DeserializeTag event handler
Private Sub OnDeserializeTag(ByVal sender As Object, ByVal e As SerializeTagEventArgs)
    Dim dataElement = e.Representation.Element("Data")
    Dim categoryId = e.Context.ReadString("CategoryId", dataElement)
    Dim orderNumber = e.Context.ReadInt("OrderNumber", dataElement)
    e.Tag = New SampleData With {.CategoryId = categoryId, .OrderNumber = orderNumber}
    e.Handled = True
End Sub