161

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>
4
  • 3
    Could you add an xml sample to this question? It would make it simpler to read along with the code. Thanks!
    – Rory
    Feb 27, 2009 at 19:30
  • What about dealing with the case where there's an XML comment etc after the last Event in your xml. ie should you finish the ReadXml() method with something that checks that you read through to the end element? Currently this assumes the last Read() does that but it might not always.
    – Rory
    Feb 27, 2009 at 19:38
  • 8
    @Rory - Sample added. Better late than never?
    – Greg
    Nov 12, 2010 at 6:34
  • @Greg Good info. Wouldn't you also want to have ReadXml and WriteXml use the Invariant Culture? I think you may run into problems if the user moved to another country and changed their Region and Language Settings. In that case the code might not correctly deserialize. I've read that it's a best practice to always use the Invariant Culture when doing serialization Jan 31, 2015 at 0:03

5 Answers 5

110

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".

7
  • What about writing out and reading the Event elements? It feels hackish to manually write the starting element. I think I've seen someone use an XmlSerializer in the write method to write each child element.
    – Greg
    Nov 11, 2008 at 21:55
  • @Greg; either usage is fine... yes, you can use a nested XmlSerializer if you need, but it isn't the only option. Nov 12, 2008 at 7:43
  • 3
    Thanks for these precisions, the sample code inside MSDN is pretty unuseful and unclear regarding this. I got stuck many times and was wondering about the asymmetric behavior of Read/WriteXml.
    – jdehaan
    Oct 19, 2009 at 10:55
  • 1
    @MarcGravell I know this is an old thread. "The framework writes a wrapper element and positions the XML writer after its start." This is where I am struggling. Is there a way to force the framework skip this step of automatically handling the wrapper? I have a situation where I need to skip this step: stackoverflow.com/questions/20885455/…
    – James
    Jan 3, 2014 at 5:00
  • @James not to the best of my knowledge Jan 3, 2014 at 7:49
38

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

4
  • Excellent article! I'll definitely reference it next time I'm looking to serialize some data.
    – Greg
    Oct 27, 2009 at 14:19
  • Thanks! the amount of positive feedback rewards the amount of time invested in writing it. I deeply appreciate that you like it! Do not hesitate to ask to criticize some points.
    – jdehaan
    Oct 27, 2009 at 14:54
  • Examples are far more useful than quoting MSDN.
    – user295190
    Jan 20, 2011 at 4:06
  • Thanks for the codeproject, I'd vote that up too, if I could. The stuff on attributes was utterly comprehensive compared to MSDN. For instance, my : IXMLSerializable class broke when prefixed by the xsd.exe generated [Serializable(), XmlType(Namespace = "MonitorService")].
    – John
    Sep 15, 2011 at 20:01
9

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.

1
  • 5
    With C# 3.0 you can probably do this by writing an extension method instead, but an interesting idea. Apr 19, 2010 at 4:10
2

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);
    }
}
2

The interface implementation is covered by the other answers, but I wanted to toss in my 2-cents for the root element.

I've learned in the past to prefer putting the root element as metadata. This has a few benefits:

  • If there is a null object, it can still serialize
  • From a code readability standpoint, it makes sense

Below is an example of a serializable dictionary where the dictionary root element is defined in that way:

using System.Collections.Generic;

[System.Xml.Serialization.XmlRoot("dictionary")]
public partial class SerializableDictionary<TKey, TValue> : Dictionary<TKey, TValue>, System.Xml.Serialization.IXmlSerializable
{
            public virtual System.Xml.Schema.XmlSchema GetSchema()
    {
        return null;
    }

    public virtual void ReadXml(System.Xml.XmlReader reader)
    {
        var keySerializer = new System.Xml.Serialization.XmlSerializer(typeof(TKey));
        var valueSerializer = new System.Xml.Serialization.XmlSerializer(typeof(TValue));
        bool wasEmpty = reader.IsEmptyElement;
        reader.Read();
        if (wasEmpty)
            return;
        while (reader.NodeType != System.Xml.XmlNodeType.EndElement)
        {
            reader.ReadStartElement("item");
            reader.ReadStartElement("key");
            TKey key = (TKey)keySerializer.Deserialize(reader);
            reader.ReadEndElement();
            reader.ReadStartElement("value");
            TValue value = (TValue)valueSerializer.Deserialize(reader);
            reader.ReadEndElement();
            Add(key, value);
            reader.ReadEndElement();
            reader.MoveToContent();
        }

        reader.ReadEndElement();
    }

    public virtual void WriteXml(System.Xml.XmlWriter writer)
    {
        var keySerializer = new System.Xml.Serialization.XmlSerializer(typeof(TKey));
        var valueSerializer = new System.Xml.Serialization.XmlSerializer(typeof(TValue));
        foreach (TKey key in Keys)
        {
            writer.WriteStartElement("item");
            writer.WriteStartElement("key");
            keySerializer.Serialize(writer, key);
            writer.WriteEndElement();
            writer.WriteStartElement("value");
            var value = this[key];
            valueSerializer.Serialize(writer, value);
            writer.WriteEndElement();
            writer.WriteEndElement();
        }
    }

    public SerializableDictionary() : base()
    {
    }

    public SerializableDictionary(IDictionary<TKey, TValue> dictionary) : base(dictionary)
    {
    }

    public SerializableDictionary(IDictionary<TKey, TValue> dictionary, IEqualityComparer<TKey> comparer) : base(dictionary, comparer)
    {
    }

    public SerializableDictionary(IEqualityComparer<TKey> comparer) : base(comparer)
    {
    }

    public SerializableDictionary(int capacity) : base(capacity)
    {
    }

    public SerializableDictionary(int capacity, IEqualityComparer<TKey> comparer) : base(capacity, comparer)
    {
    }

}
1
  • I'm catching the System.NotSupportedException: 'Can't flush final block twice' when trying to write a value with valueSerializer
    – Snail
    Oct 19, 2023 at 8:28

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.