Design Guidelines Update: Exposing XML Data

Small update to the Design Guidelines courtesy of the XML team.

System.Xml Usage

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.

Comments

• Anonymous
  June 07, 2004
  Good stuff. Keep it coming! :)
• Anonymous
  August 09, 2005
  Implementing an XmlReader is very difficult because there are over 25 abstract methods. Here's a simple way to change the problemspace to implement XmlReader with only 1 real method.
• Anonymous
  August 09, 2005
  Implementing an XmlReader is very difficult because there are over 25 abstract methods. Here's a simple way to change the problemspace to implement XmlReader with only 1 real method.
• Anonymous
  September 11, 2006
  Hi! May I aks you who did design for this site?
• Anonymous
  July 09, 2008
  PingBack from http://blowery.org/2004/06/10/systemxmlxmldocument-voldemorte/