Dundas Chart for Windows Forms
Serialization
See Also Send comments on this topic.
Working with Data > Serialization



Glossary Item Box

Overview

Serialization is the process of converting your charts into a format that allows you to efficiently save, or transmit them. The process of Serialization is mostly used to save chart properties, but can also be used to retrieve data, and load it into an existing chart control. In addition to this, any chart properties that you plan to serialize can be reset to their default values.

Remember that if the ViewStateData property is being used for state management, the Load, and Save methods of the Serializer object may be used to save and load a user-defined view state.

For more information on serializing a chart for use as a template, refer to the topic on Using Templates.

 

Format of Serialized Data

The format of serialized data is set by the Format property. The format of data can be either XML, or Binary. Each of these formats has advantages and disadvantages over the other. The advantage of XML over binary is that it is human readable, however, the binary format requires less storage space when compared to the XML format.

 

Note
When saving or loading data using an object derived from StringReader, StringWriter, XMLReader, or XMLWriter the format of the data must be XML. 

 

The default format for data is XML, and the Format property always applies to serialization regardless of what type of objects are being used to save or load the data.

 

Saving and Loading Data

Chart properties are saved by the Save method, and this serialized data is loaded into the control using the Load method. Both of these methods are members of the ChartSerializer class.

 

Note
When chart data is saved, only those properties with non-default values will be serialized. Properties that have their default values will be ignored by the serialization process.

 

By default, all of the chart's properties are saved and loaded. Both the Save and Load methods are overloaded to allow you to use them with a number of different objects. The following section describes the objects that can be used for storing saved data, or for retrieving and loading saved data.

 

Code Samples

We have included these code samples to help you get started.

Example

This example demonstrates how to serialize, then save or load, a chart's data. Its important to note that, we are saving or loading all of the chart's data, rather than setting specific chart properties to serialize and save or load.

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
  ...
  
Chart1.Serializer.Save("SavedData.xml")
Chart1.Serializer.Load("SavedData.xml")
C# Copy Code
using Dundas.Charting.WinControl;
  ...

Chart1.Serializer.Save("SavedData.xml");
Chart1.Serializer.Load("SavedData.xml");

Example

This example demonstrates how to use a stream object that derives from the .NET Stream class to save or load chart data.

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
  ...
  
Dim myStream As New System.IO.MemoryStream()
Chart1.Serializer.Save(myStream)
Chart1.Serializer.Load(myStream)
C# Copy Code
using Dundas.Charting.WinControl;
  ...

System.IO.MemoryStream myStream = new System.IO.MemoryStream();
Chart1.Serializer.Save(myStream);
Chart1.Serializer.Load(myStream);

 

An object that derives from the .NET StringReader, or StringWriter classes (for loading and saving, respectively). If the ViewStateData property is being used to manage the state data, then a StringReader object must be used to read the data into the control, and a StringWriter object must be used to write the serializable data to the ViewStateData property.

Example

This example demonstrates how to use an object that derives from the .NET XMLReader/XMLWriter classes (for loading and saving, respectively).

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
  ...
  
Dim myWriter As New System.XML.XmlTextWriter("c:\MyPersistedData.xml", System.Text.Encoding.ASCII)
Chart1.Serializer.Save(myWriter)
' We initialize the XML reader with data from a file.
Dim myXMLReader As New System.XML.XmlTextReader("c:\MyPersistedData.xml")
Chart1.Serializer.Load(myXMLReader)
C# Copy Code
using Dundas.Charting.WinControl;
  ...

System.XML.XmlTextWriter myWriter = new System.XML.XmlTextWriter("c:\\MyPersistedData.xml", System.Text.Encoding.ASCII);
Chart1.Serializer.Save(myWriter);
// We initialize the XML reader with data from a file.
System.XML.XmlTextReader myXMLReader = new System.XML.XmlTextReader("c:\\MyPersistedData.xml");
Chart1.Serializer.Load(myXMLReader);

 

Serializable Chart Properties

There are three methods by which serializable chart properties (i.e. data, visual appearance properties, etc.) can be set. The following is a description of these methods, going from the most basic to the most advanced:

  • Serialization of the Chart using the Save and Load methods without explicitly specifying any serializable properties. This will result in the serialization of all chart properties with non-default values (this includes chart data).
  • The Content property. Content groups the chart properties to be serialized into categories (e.g. data, appearance, etc.), and the names of ChartArea and Series objects are automatically serialized (the serialized data is then applied to existing chart areas and series when loaded). It is important to know that the Content property is implemented internally by the control as the SerializableContent property. This property affects all load, save and reset operations.

 

The SerializableContent property, which is a comma-separated listing of all chart properties to be serialized. The syntax of this property is "Class.Property[,Class.Property]", and wildcards may be used (represented by an asterisk). For example, to serialize all chart BackColor properties set this property to "*.BackColor".

Once this property is set to an explicit value, then it is up to you to specify all properties to be saved. If chart area and/or series child properties are specified then the names of all ChartArea and Series objects must also be specified in order to have the persisted data applied to existing ChartArea and Series objects when loaded (i.e. use "Series.Name" and "ChartArea.Name" expressions). See the sample code below for an example of this. This property affects all load, save and reset operations. The Content and SerializableContent properties can also be used in conjunction. However, make sure that SerializableContent is concatenated with itself when being set after setting the Content property (Content is implemented internally using SerializableContent with wildcards), otherwise the chart properties specified by the Content property will be overridden (see sample code below).

 

Example

This example demonstrates how to serialize all of the chart's appearance data and axis labels to disk, and then load that serialized data. Be mindful that only properties with non-default values are serialized.

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
  ...
  
' Save chart appearance properties that have non-default values, as well as axis labels.
Chart1.Serializer.Content = SerializationContent.Appearance

' We can concatenate the Content property string and the SerializableContent string, since
' the Content property is implemented internally as the SerializableContent property. Since
' we use the SerializableContent property we also need to persist the ChartArea and Series
' object's names, otherwise these serialized properties will be applied to new ChartArea 
' and Series objects when the data is loaded.
Chart1.Serializer.SerializableContent += ",DataPoint.AxisLabel,Series.AxisLabels,Series.Name,ChartArea.Name"
Chart1.Serializer.Save("AppearanceProps.xml")

' Load the serialized data.
Chart1.Serializer.Content = SerializationContent.Appearance
Chart1.Serializer.SerializableContent += ",DataPoint.AxisLabel,Series.AxisLabels,Series.Name,ChartArea.Name"
Chart1.Serializer.Load("AppearanceProps.xml")
C# Copy Code
using Dundas.Charting.WinControl;
  ...

// Save chart appearance properties that have non-default values, as well as axis labels.
Chart1.Serializer.Content = SerializationContent.Appearance;

// We can concatenate the Content property string and the SerializableContent string, since
// the Content property is implemented internally as the SerializableContent property. Since
// we use the SerializableContent property we also need to persist the ChartArea and Series
// object's names, otherwise these serialized properties will be applied to new ChartArea 
// and Series objects when the data is loaded.
Chart1.Serializer.SerializableContent += ",DataPoint.AxisLabel,Series.AxisLabels,Series.Name,ChartArea.Name";
Chart1.Serializer.Save("AppearanceProps.xml");

// Load the serialized data.
Chart1.Serializer.Content = SerializationContent.Appearance;
Chart1.Serializer.SerializableContent += ",DataPoint.AxisLabel,Series.AxisLabels,Series.Name,ChartArea.Name";
Chart1.Serializer.Load("AppearanceProps.xml");

 

Non-Serializable Chart Properties

Non-serializable properties are set using the NonSerializableContent  property. Wildcards can be used in the string expression, in the same manner as the SerializableContent property. For example, to exclude all chart BackColor properties from serialization set this property to "*.BackColor".

Sometimes a property can be set to be both serialized and not serialized (common when wildcards are used). NonSerializableContent has a lower priority when compared to the SerializableContent string expression. However, note that less weight is given to string expressions that use wildcards. For example, if SerializableContent is set to "*.BackColor" and NonSerializableContent is set to "ChartArea.BackColor" then all BackColor properties except for ChartArea objects will be serialized.

This property affects all save, load and reset operations.

 

Example

This example demonstrates how to serialize all appearance properties that have non-default values, except for all chart BackColor properties.

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
  ...
  
' Save chart appearance properties that have non-default values, except for all 
' of the BackColor properties.
Chart1.Serializer.Content = SerializationContent.Appearance
Chart1.Serializer.NonSerializableContent = *.BackColor"
Chart1.Serializer.Save("AppearanceProps.xml")
C# Copy Code
using Dundas.Charting.WinControl;
  ...

// Save chart appearance properties that have non-default values, except for all 
// of the BackColor properties.
Chart1.Serializer.Content = SerializationContent.Appearance;
Chart1.Serializer.NonSerializableContent = *.BackColor";
Chart1.Serializer.Save("AppearanceProps.xml");

 

Resetting Chart Properties to Default Values

When chart data is serialized only those properties that have had their default values changes will be persisted. This reduces the amount of data that must be saved data. Therefore, it is possible for a serializable property remain unsaved, and be reset to its default value during a load operation. If the possibility exists that a serializable property will have its default value changed after it has been saved, set the ResetWhenLoading property to False so that the default value will not overwrite the non-default value set. All properties of a chart can be reset, at any time, using the Reset method.

 

Caution
Care must be taken when resetting collection properties. If the Chart.Series, or Chart.ChartAreas attributes have been set so that specific items are persisted, then resetting the chart (i.e. ResetWhenLoading is True) will result in all Series, or ChartArea items, being deleted from the chart when the data is saved, and then reloaded. This means that all data points in the chart series will be lost.

 

See Also

©2009. All Rights Reserved.