Posts Tagged Visual Studio

C# Short Takes – 1 – XML Comments syntax for the cref attribute to a Generic Type Method


For the last couple of blog posts I have been using the XML Documentation feature of C# and Sandcastle to generate chm help files. This has resulted in help for methods I have been developing being available in many parts of the Visual Studio environment. Enabling Intelescensecontext sensitive help have proved to quite useful, and is a good thing to include with the source code I have been posting on the blog.

Things have been going quite well with this approach, until I ran into a problem with the <see/> tag and the cref attribute. This tag generates a hyperlink within the output files, after Sandcastle has processed them. These generated hyperlinks to methods in the documentation were a feature I wanted to enable in a couple of places within the generated documentation.

The Problem

The situation which caused me a headache was trying to make pair of <see/> tag elements in the XML Documentation which referenced each of a pair of generic methods. The method signatures were:

public static IEnumerable<TSource> ToIEnumerable(TSource val)
public static IEnumerable<TSource> ToIEnumerable(TSource val1, TSource val2)

The Solution

After trying a number of things and searching on the net, I discovered the following on stackoverflowC#, XML-Doc: Refering to a generic type of a generic type in C# XML documentation?. The last answer in to the question is the one that gave me the way to solve the problem.

Simply, what is required is the xml escaping of the <>I n the function name. For a full (I would expect) list of the xml escape sequences see: List of XML and HTML character entity references.

The resulting references in the <see/> tag end up as:

        /// <see cref="ToIEnumerable&lt;TSource&gt;(TSource)"/> 
 /// <see cref="ToIEnumerable&lt;TSource&gt;(TSource, TSource)"/> 

Reasoning Why It Works

This makes a degree of logical sense when you consider the resulting context of this attribute. The C# compiler translates the XML Documentation into a XML file. Within an XML file an attribute, or element, which contains a < or > character needs to have those characters translated into XML escape equivalents. Thus, the target of the link will be in an XML escaped form, so also the reference to the target should comply with the same XML escape sequences.

A Visual Studio Handy Hint

There is a built-in paste function, Edit.PasteAlterernate. The following blog post ‘What is Paste Alternate?’ describes what this function does. If you use this to paste a function signature from a C# file into a html file, you get the prototype with xml escapes included, plus a bunch of html. Using this paste variant may prove useful when you need a quick way of generating xml escapes .

In my version of Visual Studio, this function was unbound to a keystroke combination. Yu can use the Tools -> Options menu items to get up the dialogue box that allows setting the keystroke combination. The keystroke combinations are set in the Environment -> Keyboard section of this dialogue box.


I trust that reading to here, you have found blog post useful, or that it has helped solves you XML Documentation problems.

, , , , , , , , ,


Where are the Visual Studio Parallel Debug Tools?


If you are just venturing into doing things in parallel with Visual Studio this one will be of interest you.

Being someone who is starting out using Visual Studio to develop parallel tasks, I’ve watched some demonstration of the support for parallel tasks in Visual Studio. That was fine, but when I came to get those nice windows up for my project I could not find where they were hidden.

The Parallel Task and Parallel Stack Windowsclip_image002

The only way I have found to get these windows displayed is as follows:

  1. Put some breakpoints into the code which has parallel activity. I put these break points into the “bits” of code I know are off on parallel tasks.
  2. Start debugging the program.
  3. Go to the Debug Tools Tool Bar, and select the “Breakpoints” icon. This then presents the dropdown menu with the parallel tool windows.
  4. There you can see there are keyboard short cuts to open the windows. This is fine if you can get the menu up and read the shortcuts, but I could never find the option to get the menu up. Why, these items only appear when the program is in “debug mode”.



  • This is another one of those, “easy when you know how” type of things. It is not entirely obvious when you start looking for the Parallel tools where to find them.
  • There are probably (undoubtable) other ways to get these windows up, but this is the one which I have found.

, , , , , , , ,

1 Comment

Debug.WriteLine in C# 4.0 and .Net Framework 4.0


This is one is a very short blog post. There is a one improvement which has made its way into the C# 4.0 and .Net Framework, which I wish to share.

This improvement is a very simple one. If I had a paranoid streak, I would say Microsoft must have been watching the code I’ve been writing. Why? Because the code I write is littered with the following:

int i = 0;
// The old way
Debug.WriteLine(String.Format("What is i {0} - old way", i));

I use the debug output window in Visual Studio heavily. I find shoving formatted strings into the debug output window is one my standard ways of producing debug diagnostics from programs in development.

The Enhancement

public static void WriteLine(
    string format,
    params Object[] args

The above is the prototype of the addition to the Debug class, another overload of the WriteLine method. This WriteLine method is document here : Debug.WriteLine.

Simply put this is a WriteLine method which encapsulates the String.Format call. Which results in code like:

int i = 0;
// The old way
Debug.WriteLine(String.Format("What is i {0} - old way", i));
// New in Version 4 of C# and .Net Framework
Debug.WriteLine("What is i {0} - New C# 4.0 way", i);


It’s a great improvement. It will save me a lot of keystrokes when I’m developing. But this enhancement , has a downside, now I need to remember to use it!

, , , , , , , , , , ,

Leave a comment

%d bloggers like this: