I say Annotate that!!!

  Fresh off the grill or should I say warmed after deep freeze? I will leave that up to you. But I thought it was about time to let you all party on the Source Code Annotation sample, developed by one of my assistants, Chetan N Parmar at Tech Ed 2004 Visual Studio Extensibility Cook off. On second thought I am not going to call this is a sample because I don’t think it is complete enough to be a sample. I would love to have you contribute to this idea and make it an awesome, irresistibly appealing and indispensable utility for the community. How does that sound? Are you the one, Neo? What does the oracle say? Did the oracle mention that you are going to be involved in the coolest project on this earth?


Rhetoric aside I would like to invite all the gurus, mateurs alike to contribute to this project and other cool projects in near future. Let’s all work together to deliver this super cool utility that is going to help the community.  If you want to volunteer, drop the Doctor a piece of email with the area that you would like to work on.


What is this Annotation Package about?

            The primary goal of this package is to allow developers to annotate their code so they can start short discussions about a specific implementation, or tag sections in the code file that need special attention. The best of all is they can share the annotations in a team environment so other developers can contribute to the discussion. The project currently provides the following functionality:

·          Create an annotation at any given line

·          Respond to Annotations

·          Delete Annotations

·          View the annotations as text markers and in the tool window

Currently it implements a text marker service that indicates where the annotations exist on a particular file, a text marker class that draws a square arrow on the widget margin of the IDE to indicate the presence of an annotation and a tool window that allows you to manage (respond/delete) the annotations for a file. After you have built and registered the project you can load the annotations package by clicking the “Load Annotations” menu in the Solution Context menu. You can start adding annotations to a file from the code window context menu under “Annotations” sub menu. To hide the annotation, just left click on the Annotation marker in the widget margin. Enabling annotations for a solution adds an Annotation.xml file to the solution.  However this file does not yet get added to the solution so the user will not see it but it should be created in the same folder as the solution.


Here are some of the features that I feel would be great to have and are up for grabs. If you want to implement it just drop the doctor a piece of email.

·          Add the Annotations XML file to the solution

·          Support the source control scenario. When the Annotation.xml file is under Source control and someone tries to edit an annotation it should silently check out the file and edit it.

·          Track the document rename events and update the annotations appropriately

·          Convert the Annotation Manager tool window into a splitter tool window

·          Make the marker behave well with other markers sharing the same area in margin widget like the break point markers


As with all community projects this also has bugs so feel free to send them my way and I would get them addressed. Better yet, if you know the solution feel free to post the recommended change. This code was written in a very short period of time for the cook-off so don’t be surprised with any unexpected results. Since the Tech Ed all that has been done to the sample is getting rid of memory leaks and re-factoring.


Known Issues:

·          Annotation.xml file does not get added to the solution as a solution item

·          Responding to responses show up as hanging responses when viewing annotations for other files


Annotation format

<?xml version=”1.0″ encoding=”UTF-16″?>

<!– This file represents ANNOTATIONS and related Data. Do not modify this file manually. It is used by your team.–>




                                    <RESPONSE />






This package is developed using ATL. You would need the following

·          Visual Studio 2003

·          You must have the VSIP 2003 SDKinstalled, without this the Annotation package would not load


Where to get the sources:

You can download the source code for the 1.0 release of this project from here. Once you are on that page click the ‘Releases’ link under ‘Annotation Package’ panel on left side of the web page. Feel free to download the sources and party on it. If you want to join the working group and contribute to the project apply to join the Workspace through using the ‘Apply to Join this Workspace’ link on the right side under ‘Members panel. If you run into any issues you know who to contact.


Happy Annotating folks.




Dr. eX




Comments (9)

  1. Gavin Morris says:

    Hi Doc,

    Been wanting annotations in an IDE for the longest time now. Very interested in seeing where this project goes.

    Having a wretched time getting it registered with the IDE though – mostly the fact that I can’t read C++ COM code (ex Delphi developer, now C#)

    Any chance of a quick install howto in the project workspace?



  2. Dr .eX says:

    Hi Gavin,

    Hey no problem you can start implementing a C# version of this project. You need to have Visual Studio 2003 and VSIP 2003 SDK on your machine. You can then download the project build and do the following:

    1) Build the project. This will register the package under the EXP hive.

    2) Bring up Visual Studio 2003 Exp

    3) Create any project

    4) From the Solution context menu right click and execute the "Load Annotations" menu item.

    5) In the code window go to any line of code in your source file where you want to start an annotation. Right click and you should see a Annotations->Add Annotation menu. Click that to start an annotations. Once you have added an annotation a tool window pops up that you can use to manage the annotation. For e.g you can respond to the annotation, delete it, delete a response etc.

    Hope that helps


    Dr. eX

  3. Chris S. says:

    This looks like an excellent utility.

    I’d like to make a suggestion for a possible future version, that would allow for multiple types or categories of annotations.

    The reason for this, is that sometimes we may want to point out problems or suggestions, and other times we may want to describe functionality. It might be useful to be able to parse the xml file in another application to take annotations with certain categories out and place them in, say, a help file or something.

    It might also be nice to be able to turn certain categories of annotations on or off in the code, and/or jump back and forth between annotations with a specific category.

    Anyway, it seems like it would be out of scope for the current project, and perhaps it would not be worth the effort, but I think it would be good to consider it.

  4. Eric Wilson says:

    I’m trying to install this project. I can build the project just fine, but when I register the dll, nothing seems to be added to the VS7.1Exp registry keys. What exactly does it add when the Annotation.dll is registered?

  5. Dr .eX says:


    It should have automatically registered on building the pacakge sources. Do you have an Environment variable ENVSDK_REGKEY set to 7.1Exp? Do you have Whidbey installed on this machine?

  6. Hey Dr. eX

    I’m also interested in this as a way to build a code review tool. It was actually the initial reason for my downloading VSIP, but this seems much further along than my tool.

    Unfortunately, I also cannot get it to work. I have VS2003 (not Whidbey) and VSIP, and the code compiles, but I don’t get a menu item in the solution context menu (right click on the name of the solution in the solution explorer, right?). Any thoughts? Thanks.