Design Guidelines Update: Exposing XML Data

Exposing XML Data

Do provide overloads that accept and System.Xml.XmlReader and System.String for properties of a class that represent an XML document or fragment. This gives users a friendly way to access the XML by using String and an efficient way to interact with the XML via the XmlReader.

The following example shows what an implementation of this would look like. Note that it is merely illustrative and does not imply that you should always use XmlDocument as your mechanism of representing a property that is XML.

public class Email {

private XmlDocument body = new XmlDocument();

public string Body {

get { return body.OuterXml; }

set { body.Load(new System.IO.StringReader(value));}

}

public void SetBody(XmlReader reader) {

body.Load(reader);

}

public XmlReader GetBody() {

return new XmlNodeReader(body);

}

}

Do choose System.Xml.XmlReader or System.Xml.XPath.XPathNavigator as input or output for methods that accept or return XML. In the cases where the user needs to edit the XML use the XPathEditableNavigator.Using these abstractions instead of XmlDocument, XmlNode or XPathDocument as this decouples the methods from specific implementations of an in-memory XML document and also allows them to work with virtual XML data sources that expose an XmlReader or XPathNavigator.

Do implement IXPathEditable or IXPathNavigable on your classes when creating an XML view of an underlying object model or data source.

Do not create a subclass of XmlDocument if you want to create an XML view of an underlying object model or data source. This means classes like System.Xml.XmlDataDocument are an example of what not to do.

Do not use the XmlNode or XmlDocument classes as parameters to your methods. Favor using instances of IXPathNavigable or IXPathEditable instead. This decouples your API from one specific implementation of an XML data source.