My recent Extreme XML column entitled Best Practices for Representing XML in the .NET Framework  is up on MSDN. The article was motivated by Krzysztof Cwalina who asked the XML team for design guidelines for working with XML in WinFX. There had been and currently is a bit of inconsistency in how APIs in the .NET Framework represent XML and this is the first step in trying to introduce a set of best practices and guidelines.

As stated in the article there are three primary situations when developers need to consider what APIs to use for representing XML. The situations and guidelines are briefly described below:

• Classes with fields or properties that hold XML: If a class has a field or property that is an XML document or fragment, it should provide mechanisms for manipulating the property as both a string and as an XmlReader.

• Methods that accept XML input or return XML as output: Methods that accept or return XML should favor returning XmlReader or XPathNavigator unless the user is expected to be able to edit the XML data, in which case XmlDocument should be used.

• Converting an object to XML: If an object wants to provide an XML representation of itself for serialization purposes, then it should use the XmlWriter if it needs more control of the XML serialization process than what is provided by the XmlSerializer. If the object wants to provide an XML representation of itself that enables it to participate fully as a member of the XML world, such as allow XPath queries or XSLT transformations over the object, then it should implement the IXPathNavigable interface.

A piece of criticism I got from Joshua Allen was that the guidelines seemed to endorse a number of approaches instead of defining the one true approach. The reason for this is that there isn't one XML API that satisfies the different scenarios described above. In Whidbey we will be attempting to collapse the matrix of choices by expanding the capabilities of XML cursors so that there shouldn't be a distinction between situations where an API exposes an API like XmlDocument or one like XPathNavigator.  

One of the interesting design questions we've gone back and forth on is whether we have both a read-only XML cursor and read-write XML cursor (i.e. XPathNavigator2 and XPathEditor)  or a single XML cursor class which has a flag that indicates whether it is read-only or not (i.e. the approach taken by the System.IO.Stream class which has CanRead and CanWrite properties). In Whidbey beta 1 we've gone with the former approach but there is discussion on whether we should go with the latter approach in beta 2. I'm curious as to which approach developers using System.Xml would favor.