LA.NET [EN]

Apr 28

I”ve just started doing some LINQ To XML and I can assure you that the new API is really great! Just take a look at the new Object Model introduced by the System.XML.Linq assembly:

linqToXMLModel

Today I”ll just cover the basics (really a quick presentation of the most important elements you can find in the new API), but I”m thinking on writing more posts on this subject. XObject is the top base element introduced by this new XML API. It”s main objective is to let you add annotations to any element. You can see an annotation as out of band info that you can add to any element or node that is defined on an XML document. You can add a new annotation by calling the AddAnnotation method. As you”d expect, you can remove an annotation by calling the RemoveAnnotations (do notice the plural!). Interestingly, you remove an annotation by passing the type of the annotation you want to remove. Btw, the Annotations method will return a list of annotations and will also take a type to return all the annotations that match. Do keep in mind that you can  pass Object as the type and that will let you go over all the existing attributes. Here”s a really dumb example that shows how to use these methods:

var xml = new XElement(“myElem”, “Hello Xml”);
xml.AddAnnotation(“Note 1″);
xml.AddAnnotation(“Note 2″);
xml.AddAnnotation(10);

After creating an element called myElemn (which only has text content – in this case, it only has the “Hello Xml” text node), we add two string annotations and one integer annotation. If you want to go through all the annotations, you”ll need to call the Annotations method. As I”ve said, you”ll need to pass the type of annotation you want to get. If you want everything, you can simply pass Object, as the next snippet shows:

foreach (var note in xml.Annotations()) { Console.WriteLine(note); }

ok,simple stuff,right? Again, removing an existing annotation is really really simple: just call the RemoveAnnotation method and pass it a type. The next snippet shows you how to remove all the string annotations:

xml.RemoveAnnotations<String>();

All of these methods have overloads: one that uses generics and another that receives the type as a parameter. Now, when I used Reflector to see the code, I couldn”t stop noticing that there is duplicate code across both implementations which ends up doing the same thing. wtf? Not sure on why the generic method doesn”t just redirect to the non-generic one by passing typeof(T)…I want to believe that I”m missing something…

Still on the annotations, I”m assuming that you”ll be using this only for adding important info to a node or an attribute. For instance, if you”re building a XML tree from an existing order object, you might find it useful to add that order object as an annotation to your top XML element order node so that you can reuse it later when you”re processing the XML tree.

Going back to the model, and since today it”s all about the basics, I”ll just wrap this post by presenting each of the elements I”ve just shown you in the previous figure:

  • XAttribute: You”ve guessed it! You”ll use this object to represent an existing attribute.
  • XNode: the base class of all of the XML nodes that might exist on a XML tree. This class adds several important methods that will let you go through some of the axis that exist on an element. For instance, you can call the Ancestors method to get a collection with all the parent nodes of the current element;
  • XComment: used for letting you add XML comments to a XML tree;
  • XContainer: used for all elements that can be used as containers in a document. In practice, this means an XML element or an XML document.
  • XDocumentType: Lets you add a DTD to an XML document. It”s important to notice that DTD support is limited on this API (If  you want to know more, read this);
  • XProcessingInstruction: as you can infer from its name, we”re talking about processing instructions here.
  • XText: used to represent a text node. If you need escaping, then you should use the XCData class.
  • XDocument: represents an XML document. Most of the time, you”ll end up working with the XElement class. However, if you need set up a processing instruction or if you need to set a DTD, you”ll necessarily have to use a XDocument instance.

Besides those classes, there at least 2 important classes defined on the System.XML.Linq namespace:

  • XName: used to represent an XML name. As you”ll see in future posts, this class makes working with XML names quite painless (I do really love this class!);
  • XNamespace: used to represent an XML namespace. As you”ll see in future posts, this and previous class are priceless when you think on querying or building an XML tree that uses namespaces.

And I believe this is quite long for an intro post. We”ll start with the cool stuff on the next day. Keep tuned.

Leave a Reply

Your email address will not be published. Required fields are marked *


*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>