Tobi + C# = T#

Hi folks,
a few days ago I figured out how to create HTML help files from code comments and how
to integrate them into visual studio so pressing F1 on one of my classes opens the
generated help file.
Because I spent much time googleing the world getting all information I needed I decided
to write down how I did it:

1. Download and install tools

- Sandcatle

- Sandcastle Help File Builder

- HTML Help 2.0 compiler
The Help 2.0 compiler is integrated into the VS SDK (VS2005) (VC2008)

The compiler will be installed in the directory “%Program Files%\Common Files\Microsoft Shared\Help 2.0 Compiler\”.
Search for hxcomp.exe if you can’t locate it.

2. Configure Visual Studio to generate XML comment file

Open Project properties. Select Build tab and ensure that the checkbox “XML documentation file” is checked.
Then recompile your project.

3. Configure Sandcastle Help Builder

Create a new project and add your assembly to the project. Ensure that an xml file was found too. The added
entry should look like “MyAssembly.dll, MyAssembly.xml” and not like “MyAssembly.dll, Unknown.xml”. In this case
your xml documentation file was not found and a documentation cannot be build.

Lets go on with the settings:

Build > Help File Format: Enable HtmlHelp2x
Build > Dependencies: Add all assemblies your assembly depends on here.
Build > Framework Version: Select the .NET Framework version your assembly is build on.
Help File > Presentation Style: Select vs2005. This is not neccessary but pretty.
Paths > HtmlHelp2xCompilerPath: Give the path to the directory where hxcomp.exe is located.
Paths > SandcastpePath: Set it to the correct installed sandcastle path. In my case I had multiple versions
of sandcastle installed and had to specify where the newest version is installed.

4. Build help file

Now you should be able to build your help file. You cannot view Help 2 files without special viewers.
So build HTML Help 1.x files first until your output fits your needs. Play around with the
settings and define style, disable warning and define what you want to be documented.
Finally build a HTML help 2.0 file if your want to get it integrated into the Visual Studio
help system and go on with the next step.

5. Integrate help file into Visual Studio

Run Visual Studio.
Select File > New Project.
Select Other Project Types > Extensibility > Help Integration Wizard
In the first assistant step leave “Setup project” selected, chose your Visual Studio version and go next.
In the second assistant step add your Html Help 2 files (*.hxs).
Configure the last two steps as you wish.
Build the project.
Run the created setup which installes your help files into visual studio.

That’s it! Happy Easter!

Alexander

Tweet this

Just a quick note:

There is a way to convert a .sln to a msbuild file.

All you have to do is open the Visual Studio 2008 Command Prompt and set an environment variable - it's that simple.

and execute

After a successful compile there will be a solutionname.sln.proj file - which is a complete msbuild representation of the .sln.

Tweet this

I just had to convert a Visual Studio 2008 Solution and Project to Visual Studio 2005, because we had to exchange sources with somebody who did not use VS 2008 yet.

Even though Microsoft (of course ) did not provide a wizard or automated tool for it, converting the solution is possible to do, if you know what you are doing. It is actually pretty straight forward. At least in my case... I really can't tell if it is always that easy.

All I had to do in the .sln file:
change

to

The .csproj is more complicated (showing changes as diff):

The "-" at the start of a line means remove from 2008 version and a "+" means add to 2005 version. For more explanation see Diff Section "unified format".

Hope this helps in case you need to do the same.

Tweet this

As promised Microsoft did actually release the .NET Framework Source Code for us developer to seamlessly step through. Awesome!

Read more about how to configure VS to load symbols for the framework at Shawn Burke's Blog.

All I need now is a debug shortcut that let's me choose if I want to enable the symbol server or not. Something like: hit F5 and VS ignores the symbol server and lets me only debug my local sources (= behave as if "Enable Just My Code" is checked and "Enable source server support" is not checked). That should be the default scenario, because 99% of debugging is actually debugging something I broke. But I also want a shortcut like Shift+F5 (which currently is Debug.Stop) which loads all needed symbols on starting the debugging (= behave as if "Enable Just My Code" is not checked and "Enable source server support" is checked, plus "Search the above locations only when symbols are loaded manually" is NOT checked). That way I could step into

by means of F11 without the need of a Call Stack or manually adding the symbols. Which would be handy, if there is an exception coming out of the framework that I don't understand (the other 1% of debugging).

Well, whatever. Now I switch the behaviour manually, which is just fine. Because today I did play a bit with the source view of the framework. But I didn't really need it (yet). We'll see.

Oh, and I would really, really love it if you could include symbols for System.ServiceModel very, very soon. Because unfortunatelly it is not included yet, and for me it has been the source of most exception that I did not understand.

Tweet this

Well, at work (and at home) I have moved to Visual Studio 2008 quite some time ago. But there simply are a lot of solutions and projects around from the pre 2008 era. Not just in our (or my) source control, but almost any OS project on the web has not moved to 2008 (yet). And there are loads of examples that are still using 2003 solutions.

So any time I come across one of those I always wince. Just the thought of going through the next few steps, just the anticipation gives me a serious headache every time. Because noooo, I can't just double click on the solution and be done with. Nope, somebody at Microsoft was clever and managed to version brand those solutions. So if I can't catch the little 8 instead of the 9 in the icon (!) of the solution file ... my visual studio 2005 will open. Argh. So now that guy managed to brand me into "look really, really close at the icon, dude". And I don't like that. I want to have a SETTING that overrides this stupid behavior. It just does not make sense to me. Because the only option to turn off that behavior is - to uninstall VS2005. Well, that's number one of the settings I am really, really missing. But that's not even the worst part, I can reason with that - it's a cross program behavior and maybe they don't want to mess with that.

What I really don't get is that there still is no way to default the hidious Visual Studio Conversion Wizard to

• Don't show up. (I really, really don't care)
• Convert without backup. (who needs a backup in the age of source control)
• ... and don't bother with the little check mark about "Show the conversion log when blablabla". If I want to see it I KNOW WHERE TO FIND IT.

Stupid Dear Visual Studio Conversion Wirzard: Please, please, pretty please, do only EVER pipe up if there actually was an error. No, actually, even then, don't pipe up. In that case just silently open the conversion log. I'll KNOW what you mean by it. And oh, if you find a reference to a 2008 csproj file in a 2005 sln THAT does NOT count as an error. Be happy that you DON'T have to do ANYTHING about it and walk away.

Please Visual Studio Conversion Wizard Writing Guy, please save my time and my nerves and implement a little tiny minuscule setting to make me happy. Please. The VS migration experience would really benefit.

Tweet this

In my Codegeneration-Addin for Visual Studio 2008 i tried to add an attribute to my generated getter and setter with the method "AddAttribute"

At runtime I get an error with the nice message "Unbekannter Fehler" (unknown Error). It seems that the error only appears at getter/setter (CodeFunction). At "CodeProperty" and "CodeClass" everything works fine. Strange.

Tweet this

Have you ever used the Code Definition Window in VS 2005/2008? If you have not, I strongly suggest you try it out. It is a feature that is 4 years old, but still manages to amaze me and is a true help while coding. You will find yourself hitting F12 less and less. Especially when you are coding using multiple monitors. Me for example, I have the Code Definition Window as a floating window on my second monitor.

Why do I bring up that feature now? Well, lately I have gone to the dark side of VS. (Btw I nearly pissed myself when I found that URL while writing this post! Great humor, Darius.)

"Is the dark side stronger?" "No, no, no. Quicker to code, easier on the eyes, more seductive." "But how am I to know the good side from the bad?" "When it looks like vim!"

Anyway, it seems as if the Code Definition Window does a screen refresh using the colour white even when a dark background is selected. So now I feel like I am getting photographed every few seconds. This is a very annoying bug. And I sure don't know what to do, because I don't want to go back to the light side and using a light background on my current font colours is just not an option either. Damn.

Well, besides that I found out another fun thing; the Code Definition Window even knows how to resolve the new var keyword (at least when there are no anonymous types involved). Fun.

Nothing more will I teach you today. Clear your mind of questions.

Tweet this

Well, a couple of days ago a coworker and I came across a very strange behaviour concerning Expression Blend while binding to a generic list of an interface. And we were able to reproduce the same behaviour in Visual Studion 2008 as well.

In our example ObservableCollection, where Mitarbeiter is the German word for employee. Sorry about the German throughout the example, but I am currently waiting to board my plane and I did not have enought time to reproduce the screenshot with a purely English example. Well, treat it as your first lesson in German.

Anyway, so IMitarbeiter is the interface describing an employee and here is the important part: it is derived from another interface IPerson (where you are in luck, because German Person = English person. Great stuff, hugh?)

So basically the interface is:

EMail = email (dugh) Arbeitsplatz = working space

And here is the definition for IPerson:

Name = name (double dugh) Bild = picture Beschreibung = description

So. As I said the interface IMitarbeiter is now used to define a generic list ObservableCollection which we now want to bind to a WPF interface using Expression Blend. We do not worry about where this ObservableCollection comes from (since I know you are going to as: it come from some distant, well capsulated business tier, going through a GUI specific processing layer using MVP and blablabla... ), we are stricktly concerned with interface matters.

All that is done by the developer is create this codebehind:

So we are firing up Expression Blend and start doing the object binding, go to the "Create Data Template" Dialog and see this:

So we ONLY see the stuff defined in IMitarbeiter. No Fields coming from IPerson! Why that is is absolutely not clear. Most likely the deverloper of the code that does the reflection to analyse the interface did pass the wrong value that controlled the walking of the inheritance tree. The fun part is: This behaviour is totally reproducable in ASP.NET's databinding as well.

I have to emphasis, this is absolutely a GUI bug. When handcoding against the interface's properties everything works as expected.

I am sorry about this hurried post - but actually we started boarding and I am the last person sitting out her - and the nice lady behind the counter is starting to give me some nasty looks. Gotta go.

Tweet this

Lars and I did some porting of a VS 2005 vsPackage to VS 2008. And we were quite shocked by this:

Fortunatelly those 30 something compile errors are "just" caused by a couple of duplicated namespaces and classes existing both in Microsoft.VisualStudio.Shell.9.0.dll and Microsoft.VisualStudio.Shell.dll, like Microsoft.VisualStudio.Shell.RegistrationAttribute or ServiceProvider. One solution would be to remove the reference to Microsoft.VisualStudio.Shell.dll and just use the new version. Unfortunatelly we still needed the reference for some obscure reasons. But introducing an alias for the old library helped - and made all the errors go away. Fortunatelly.

So, go to the References section in your project, click on Microsoft.VisualStudio.Shell and change the Property "Aliases" from "global" to something like "oldShell". It worked for us, I hope it works for you - and allows you to port your vsPackage as well. Good luck.

Tweet this

After installing Visual Studio 2008 my first goal was it to create a Visual Studio AddIn that implements an interface with all variables, properties and methods. After everything was done (I am going to describe it in detail in my next post) I wanted to make a deployment package. At microsoft.com I found a really cool How To Deploy a vsPackage Video for Visual Studio 2005 that helps to understand the creation of a setup.

One important step is creating all the Registry-Settings. This is done using RegPkg.exe, which can be found in the SDK-Bin-Folder. Using it with the parameter "/root", you can set the Registry-Path of your Visual Studio.

Here you have to be careful. If you include a final backslash (e.g. /root:SOFTWARE\Microsoft\VisualStudio\9.0\) RegPkg.exe generates a Reg-File with wrong pathvalues. You have to repair the Reg-File or generate a new one without backslash.

Tweet this