LINQ to XML techniques: adding a processing instruction

In this post we saw how to add a declaration to an XML document. A well-formatted XML document starts with a declaration whose main function is to declare formally that the upcoming document is of the XML type. The XDeclaration object helps us to easily add a declaration to an XML document. Note that the XDocument.ToString method does not print the declaration for some reason so we need to print it separately if needed.

In this post we’ll see how to add a processing instruction to an XML document.

A processing instruction declares an action that should be carried out on the document. These instructions do not add to the contents of the document, i.e. they do not belong to the actual information conveyed by the document. A good example is when a stylesheet is added to render the document in some way. However, a processing instruction is not something that XML processing software will automatically understand and act upon. It won’t raise an exception if there’s anything wrong with an instruction since there are no pre-defined nodes and attributes attached to an instruction. If your code encounters an instruction then you’ll need to know what it means and what to do with it otherwise it will go unnoticed.

As a result, processing instructions are rarely added to XML documents in reality.

The XProcessingInstruction represents a processing instruction. Let’s see how to add an XML stylesheet reference and some fancy comments to an XML document. Note that these instructions can be added at various levels of the document:

XDocument bandsDocument = new XDocument(
	new XProcessingInstruction("xml-stylesheet", "mystyle.css"),
	new XElement("Bands",
		new XElement("Band",
			new XAttribute("genre", "rock"),
			new XElement("Name", "Queen"),
			new XElement("NumberOfMembers", 4)),
		new XElement("Band",
			new XAttribute("genre", "progressive"),
			new XElement("Name", "Genesis"),
			new XElement("NumberOfMembers", 5)),
		new XElement("Band",
			new XProcessingInstruction("comment", "this-is-a-comment"),
			new XAttribute("genre", "metal"),
			new XElement("Name", "Metallica"),
			new XElement("NumberOfMembers", 4))));

The above code generates the following document:

<?xml-stylesheet mystyle.css?>
<Bands>
  <Band genre="rock">
    <Name>Queen</Name>
    <NumberOfMembers>4</NumberOfMembers>
  </Band>
  <Band genre="progressive">
    <Name>Genesis</Name>
    <NumberOfMembers>5</NumberOfMembers>
  </Band>
  <Band genre="metal">
    <?comment this-is-a-comment?>
    <Name>Metallica</Name>
    <NumberOfMembers>4</NumberOfMembers>
  </Band>
</Bands>

Processing instructions can be added to an XDocument after it has been initialised using the various Add methods. Here we add the instruction as the first node to the document:

XDocument bandsDocument2 = new XDocument(
	new XElement("Bands",
		new XElement("Band",
			new XAttribute("genre", "rock"),
			new XElement("Name", "Queen"),
			new XElement("NumberOfMembers", 4)),
		new XElement("Band",
			new XAttribute("genre", "progressive"),
			new XElement("Name", "Genesis"),
			new XElement("NumberOfMembers", 5)),
		new XElement("Band",
			new XAttribute("genre", "metal"),
			new XElement("Name", "Metallica"),
			new XElement("NumberOfMembers", 4))));
bandsDocument2.AddFirst(new XProcessingInstruction("comment", "this-is-some-comment"));

You can view all LINQ-related posts on this blog here.