Most good .NET developers consult the MSDN Library frequently. On the whole, the Library is comprehensive and accurate. Its quality is not quite on the level of UNIX manual pages, but it has improved over the years. Still, one problem persists: too often, the focus is on happy paths, and edge cases are ignored. This results in the occasional nasty surprise.

Such was the cause of a recent bug in my client’s product. Let’s examine the Library article on the XPathNavigator.MoveToRoot() method:

Moves the XPathNavigator to the root node that the current node belongs to.

All nodes belong to one and only one document. Therefore, this method is always successful.

This seems about as unambiguous as it gets. Unfortunately, a key detail is missing. More than one type of node can be considered root, and which one is root in a particular case depends on how the underlying XML document was constructed. For XPathNavigator instances constructed over XmlDocuments, MoveToRoot() can move to either the owning XmlDocument OR the root XmlElement.

In the following example, the navigator initially is positioned on a child node. MoveToRoot() moves to the owning XmlDocument.

If we omit the AppendChild() call on the document (something commonly done), MoveToRoot() instead moves to the root XmlElement:

It’s understandable why this quirk is not documented. XPathNavigator is an abstract class. It has no affinity towards any of the various XML APIs in the Base Class Library. The framework provides a number of concrete subclasses that adapt XPathNavigator to each API. Ideally, per-API edge cases would be documented in the MSDN Library article for each concrete subclass. Those classes, however, aren’t public. Since there’s no good place to document the quirks, this quirk isn’t documented.

There are a zillion posts out there that describe how to use DebuggerDisplayAttribute. They all say about the same thing: put property names and other expressions inside curly braces. Like this:

Voilà! The debugger experience has just been enriched.

So curly braces are special. That’s great, but what if you want to include an actual curly brace in the display? Some of the .NET Base Class Library’s own types display in the debugger with curly braces – System.Type, for example. Unfortunately, most articles (including MSDN, as of this writing) don’t explain how to accomplish this.

To display a curly brace, just escape it with a backslash:

Notice that the template string now is a verbatim string literal (@"..."). That is because we do not want the compiler to interpret \{ and \} as escape sequences. Neither are valid C# escape sequences, and your code won’t build if you try to use them as such. Rather, \{ and \} are interpreted by the debugger at runtime. Thus, the backslashes themselves need to be compiled into the assembly verbatim.

In summary:

  • Use \{ and \} to display curly braces when using DebuggerDisplayAttribute
  • Use @"..." string literals if you want to use \{ or \}.

This Blog Exists

April 17, 2012

This blog exists.  Now, if only there were some content here, eh?