Archive for category Visual Studio 2010

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


Introduction

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.

Conclusions

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

, , , , , , , , ,

5 Comments

Where are the Visual Studio Parallel Debug Tools?


Introduction

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”.

 

Conclusions

  • 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

Visual Web Developer Team Blog : Visual Studio 2010 Beta 2 – Intellisense Issue in Javascript/HTML.


 

Visual Web Developer Team Blog : Visual Studio 2010 Beta 2 – Intellisense Issue in Javascript/HTML.

This bug bit me.

I have just starting out playing with HTML, and Visual Studio 2010 was the first version I’d tried playing in. I was disappointed that Visual Studio was not giving me:

  • Intellisense for the HTML tags,
  • Intellisense for imbedded CSS elements (yes, I’ve developed that far), or
  • A properties editor for the HTML elements.

All of these are symptoms of the bug, which the above link describes how to fix.

The quick fix, edit the registry did not work for me. The second fix, Tools –> Import/Export Settings –> Just rest, Don’t Save –> Web Development –> Finish. Did work, all of the features which were not working, now function correctly. What a change for the better.

How did I tumble to it being a problem with VS 2010 Beta 2? At work I was going to create a HTML signature for my Notes Mail, the only way to put font information onto the signature block. I have developed an overt hatred for “Default Sans Serif”, which is what Notes is deciding I should be using. At work I’ve VS 2008, and lo and behold all of the above features were working.

Conclusion

This fix has probably saved me a bucket of money. I was toying with the idea of buying Microsoft Expression to give me a “smart” Web development platform. But as they say in the classics, “I’ll keep my powder dry” on that choice, although I may go for the upgrade from an Office product solution.

Digg This

, , , , ,

Leave a comment

%d bloggers like this: