How NOT to write Code Examples

When working on one of my pet projects, I need to extend the visual studio IDE. Before starting out I wanted to get a better understanding of the IDE extensibility model. Therefore I allocated  some time to do a spike in order to get a feeling of the basic capabilities and the effort that will be involved. Usually when doing spikes I  like to dirty my hands as soon as possible, so I thought that best way would be to create my own sample add-in and play with it.

So the first step of business was to create my own add-in project, that was fairly easy to accomplish since there's a build in wizard for creating an add-in project (it hides under other project types-> extensibility:

The next step for me was to try an add a custom menu command to be able to insert some custom logic and check out its behavior. It didn't took me long and I found the following article on MSDN: How to: Expose an Add-in on the Tools Menu (Visual C#).

After reading the initial description:

When you create an add-in by using the Add-In Wizard and select the option to display it as a command, the command is on the Tools menu by default. If you skip this option when you create the add-in, however, you can simply run the Add-In Wizard again, check that option, and then copy your existing code to the new add-in.

If doing this is not possible, though, the following procedure produces the same result.

I was encouraged. This was exactly what I needed.

So I went ahead and followed the instruction titled:

To add a menu command to an existing add-in

The first step was to copy paste a  given piece of code:

1. Replace or change the add-in's Connect class and OnConnection() procedure code to the following:

(actual code can be found in the article itself)

Followed by copy pasting 2 new methods:

2. Add the following two required procedures, QueryStatus and Exec

(actual code can be found in the article itself)

and that's it.

easily enough I did those things and went on to compile and test it (a nice thing about the add-in wizard is that it takes care of deploying the add-in and it puts in the debug command line what you need in order to safely open a new IDE instance with the updated add-in.)

did it work?

Of course not (otherwise I wouldn't be writing this post would I?)

Actually it was far worse then not working at all. When trying to figure what was wrong, I got this irritating inconsistent behavior that didn't point me in any way to what was causing it. At first I did something wrong, so I went ahead and did everything again (from scratch). Naturally that didn't help. Then I went and tried other examples from the web for the OnConnect method, but still nothing.

To make a long story short, after several frustrating hours debugging, I took the needed break and went back to reread the MSDN article. This time I paid extra attention to all parts. At the end of the article there was the following paragraph:

Each time you implement IDTCommandTarget, you must add these two procedures. A quick way to do it is to select IDTCommandTarget in the Class Name drop-down box at the top-left corner of the editor. Select each procedure in turn from the Method Name drop-down box in the top-right corner. This creates the necessary empty procedures with the correct parameters to which you can then add code.

The Exec procedure is called when a user clicks your menu command, so insert code there that you want to execute at that time.

Don't get me wrong. I read the entire article twice before, but on the third time it hit me. The Connect class needed to implement the IDTCOmmandTarget class. And  since the wizard which created the class didn't do so and nowhere in the article it was mentioned explicitly I didn't add it myself.

Lesson Learnt?

Well the obvious one would be

when everything else fails read the f***** manual

but that would be a cliche.

The actual message I'm trying to sent out here is meant for all those writing API documentation, articles and other code examples.

Please make the extra step and try your own examples before publishing them. Not on your personal machine. Try them out in a clean system where you mimic (as closely as possible) the steps that will be taken by those using the examples. Several hours would have been spared me (and probably for others as well) if that was done in this case.

Posted in: Add-in,bugs,Documentation,IDE