Proper way to implement IXmlSerializable?
Once a programmer decides to implement IXmlSerializable, what are the rules and best practices for implementing it? I've heard that GetSchema() should return null and ReadXml should move to the next element before returning. Is this true? And what about WriteXml - should it write a root element for the object or is it assumed that the root is already written? How should child objects be treated and written?
Here's a sample of what I have now. I'll update it as I get good responses.
public class MyCalendar : IXmlSerializable
{
private string _name;
private bool _enabled;
private Color _color;
private List<MyEvent> _events = new List<MyEvent>();
public XmlSchema GetSchema() { return null; }
public void ReadXml(XmlReader reader)
{
if (reader.MoveToContent() == XmlNodeType.Element && reader.LocalName == "MyCalendar")
{
_name = reader["Name"];
_enabled = Boolean.Parse(reader["Enabled"]);
_color = Color.FromArgb(Int32.Parse(reader["Color"]));
if (reader.ReadToDescendant("MyEvent"))
{
while (reader.MoveToContent() == XmlNodeType.Element && reader.LocalName == "MyEvent")
{
MyEvent evt = new MyEvent();
evt.ReadXml(reader);
_events.Add(evt);
}
}
reader.Read();
}
}
public void WriteXml(XmlWriter writer)
{
writer.WriteAttributeString("Name", _name);
writer.WriteAttributeString("Enabled", _enabled.ToString());
writer.WriteAttributeString("Color", _color.ToArgb().ToString());
foreach (MyEvent evt in _events)
{
writer.WriteStartElement("MyEvent");
evt.WriteXml(writer);
writer.WriteEndElement();
}
}
}
public class MyEvent : IXmlSerializable
{
private string _title;
private DateTime _start;
private DateTime _stop;
public XmlSchema GetSchema() { return null; }
public void ReadXml(XmlReader reader)
{
if (reader.MoveToContent() == XmlNodeType.Element && reader.LocalName == "MyEvent")
{
_title = reader["Title"];
_start = DateTime.FromBinary(Int64.Parse(reader["Start"]));
_stop = DateTime.FromBinary(Int64.Parse(reader["Stop"]));
reader.Read();
}
}
public void WriteXml(XmlWriter writer)
{
writer.WriteAttributeString("Title", _title);
writer.WriteAttributeString("Start", _start.ToBinary().ToString());
writer.WriteAttributeString("Stop", _stop.ToBinary().ToString());
}
}
Corresponding Sample XML
<MyCalendar Name="Master Plan" Enabled="True" Color="-14069085">
<MyEvent Title="Write Code" Start="-8589241828854775808" Stop="-8589241756854775808" />
<MyEvent Title="???" Start="-8589241828854775808" Stop="-8589241756854775808" />
<MyEvent Title="Profit!" Start="-8589247048854775808" Stop="-8589246976854775808" />
</MyCalendar>
Yes, GetSchema() should return null.
IXmlSerializable.GetSchema Method This method is reserved and should not be used. When implementing the IXmlSerializable interface, you should return a null reference (Nothing in Visual Basic) from this method, and instead, if specifying a custom schema is required, apply the XmlSchemaProviderAttribute to the class.
For both read and write, the object element has already been written, so you don't need to add an outer element in write. For example, you can just start reading/writing attributes in the two.
For write:
The WriteXml implementation you provide should write out the XML representation of the object. The framework writes a wrapper element and positions the XML writer after its start. Your implementation may write its contents, including child elements. The framework then closes the wrapper element.
And for read:
The ReadXml method must reconstitute your object using the information that was written by the WriteXml method.
When this method is called, the reader is positioned at the start of the element that wraps the information for your type. That is, just before the start tag that indicates the beginning of a serialized object. When this method returns, it must have read the entire element from beginning to end, including all of its contents. Unlike the WriteXml method, the framework does not handle the wrapper element automatically. Your implementation must do so. Failing to observe these positioning rules may cause code to generate unexpected runtime exceptions or corrupt data.
I'll agree that is a little unclear, but it boils down to "it is your job to Read() the end-element tag of the wrapper".
I wrote one article on the subject with samples as the MSDN documentation is by now quite unclear and the examples you can find on the web are most of the time incorrectly implemented.
Pitfalls are handling of locales and empty elements beside what Marc Gravell already mentioned.
http://www.codeproject.com/KB/XML/ImplementIXmlSerializable.aspx
Yes, the whole thing is a bit of a minefield, isn't it? Marc Gravell's answer pretty much covers it, but I'd like to add that in a project I worked on we found it quite awkward to have to manually write the outer XML element. It also resulted in inconsistent XML element names for objects of the same type.
Our solution was to define our own IXmlSerializable interface, derived from the system one, which added a method called WriteOuterXml(). As you can guess, this method would simply write the outer element, then call WriteXml(), then write the end of the element. Of course, the system XML serializer wouldn't call this method, so it was only useful when we did our own serialization, so that may or may not be helpful in your case. Similarly, we added a ReadContentXml() method, which didn't read the outer element, only its content.
If you already have an XmlDocument representation of your class or prefer the XmlDocument way of working with XML structures, a quick and dirty way of implementing IXmlSerializable is to just pass this xmldoc to the various functions.
WARNING: XmlDocument (and/or XDocument) is an order of magnitude slower than xmlreader/writer, so if performance is an absolute requirement, this solution is not for you!
class ExampleBaseClass : IXmlSerializable {
public XmlDocument xmlDocument { get; set; }
public XmlSchema GetSchema()
{
return null;
}
public void ReadXml(XmlReader reader)
{
xmlDocument.Load(reader);
}
public void WriteXml(XmlWriter writer)
{
xmlDocument.WriteTo(writer);
}
}