Dr. eX's Blog : Add-ins

Using IVsProfferCommands to retrieve a Visual Studio CommandBar

Dr. Ex — Tue, 17 Apr 2007 23:03:00 GMT

If you are an add-in developer, you are probably familiar with adding menu items and toolbar buttons to the Visual Studio environment. In most instances add-in developers take their cue from the code generated by the Visual Studio Add-in Project Wizard.

For example, the following code is generated when you create a new C# add-in project and select the “Create Command Bar UI” check box in the add-in project wizard.

public void OnConnection(object application, ext_ConnectMode connectMode, object addInInst,
ref Array custom)

{

_applicationObject = (DTE2)application;

_addInInstance = (AddIn)addInInst;

if(connectMode == ext_ConnectMode.ext_cm_UISetup)

{

object []contextGUIDS = new object[] { };

Commands2 commands = (Commands2)_applicationObject.Commands;

string toolsMenuName = "Tools";

// Find the MenuBar command bar, which is the top-level command bar holding all
// the main menu items:

CommandBar menuBarCommandBar = ((CommandBars)_applicationObject.CommandBars)["MenuBar"];

// Find the Tools command bar on the MenuBar command bar:

CommandBarControl toolsControl = menuBarCommandBar.Controls[toolsMenuName];

CommandBarPopup toolsPopup = (CommandBarPopup)toolsControl;

try

{

//Add a command to the Commands collection:

Command command = commands.AddNamedCommand2(_addInInstance, "My Command", "My Command",

"Executes My Command", true, 59, ref contextGUIDS,

(int)vsCommandStatus.vsCommandStatusSupported +

(int)vsCommandStatus.vsCommandStatusEnabled,

(int)vsCommandStyle.vsCommandStylePictAndText,

vsCommandControlType.vsCommandControlTypeButton);

//Add a control for the command to the tools menu:

if((command != null) && (toolsPopup != null))

command.AddControl(toolsPopup.CommandBar, 1);

}

catch(System.ArgumentException)

{

}

In the code sample above, a new command (“My Command”) is added to the Tools menu. Note how this particular sample retrieves the CommandBar for the “Tools” menu, by way of the Controls collection on the CommandBar representing the main IDE menu named “MenuBar”.

This is the preferred technique for retrieving a CommandBar representing a menu on the main IDE menu, because in theory there could be other CommandBar objects named “Tools” in the DTE.CommandBars collection.

The Problem:

The above mentioned code however, does not account for when the user manually removes the “Tools” menu. Nor does it take into consideration that some add-in or Visual Studio Package may have added an identically named toolbar or menu to the environment.

Consider the following Visual Studio macro:

Sub PrintCmdBarNames()

Dim ow As OutputWindow = DTE.Windows.Item(Constants.vsWindowKindOutput).Object

Dim pane As OutputWindowPane

Try

pane = ow.OutputWindowPanes.Item("CommandBar Names")

Catch ex As Exception

pane = ow.OutputWindowPanes.Add("CommandBar Names")

End Try

pane.Clear()

Dim nameList As New List(Of String)

For Each cmdBar As CommandBar In DTE.CommandBars

nameList.Add(cmdBar.Name)

nameList.Sort()

For Each name As String In nameList

pane.OutputString(name & vbCr)

End Sub

When run, the above macro displays a sorted list of CommandBar names, contained in the DTE.CommandBars collection. Note, that many of the names listed are duplicated.

Given that CommandBars can have identical names; that users may change the Visual Studio IDE’s menu layout; and third parties can add additional menus with identical names to the IDE, it becomes very difficult to retrieve a specific CommandBar from the DTE.CommandBars collection.

The Solution:

If you are a Visual Studio Package developer, you are probably familiar with using .CTC files to add new menus, toolbars and commands to the Visual Studio IDE. For the uninitiated or curious, please refer to the documentation and samples included with the Visual Studio SDK. To briefly summarize, each command, menu and toolbar added via a .CTC file, is uniquely identified by a GUID:ID pair. This GUID:ID pair can be used with the IVsProfferCommands.FindCommandBar method, to retrieve a specific CommandBar object.

Finding the GUID:ID pair for a particular menu or command can be a hit or miss affair. You could search the various .IDL, .CTC, and .H files included with the Visual Studio SDK, or post a message in the MSDN Extensibility Forum and hope for a response. But with Visual Studio SP1, you can now use the undocumented but extremely useful EnableVSIPLogging registry value to help find the GUID:ID pair that indentifies the specific menu or command you are interested in. You can learn more about the EnableVSIPLogging registry value in the Dr. eX blog post entitled “Using EnableVSIPLogging to identify menus and commands with VS 2005 + SP1”.

The IVsProfferCommands interface is defined in the EnvDTE namespace, but is marked for “Microsoft Internal Use Only”. However, given the need for a solution to the problem defined above, and after consulting with the Visual Studio development team, Dr. eX, and the VS IDE development team feel comfortable recommending this as a viable solution for both add-in and package developers.

The IVsProfferCommands interface can be retrieved by calling QueryService on the DTE object’s IOleServiceProvider interface. Note this IOleServiceProvider is the OLE/COM equivalent of the .Net IServiceProvider. However, these two interfaces are different, and you need to use the OLE/COM version of this interface to successfully retrieve the IVsProfferCommands service. This interface is defined in the Microsoft.VisualStudio.OLE.Interop.dll assembly that ships with the Visual Studio SDK. But you can readily define this interface yourself, without having to download the Visual Studio SDK.

For example:

[

ComImport,

Guid("6D5140C1-7436-11CE-8034-00AA006009FA"),

InterfaceTypeAttribute(ComInterfaceType.InterfaceIsIUnknown)

]

internal interface IOleServiceProvider

{

[PreserveSig]

int QueryService([In]ref Guid guidService, [In]ref Guid riid,
[MarshalAs(UnmanagedType.Interface)] out System.Object obj);

}

Then it is just a matter of calling QueryService to retrieve the IVsProfferCommands interface, and then invoking IVsProfferCommands.FindCommandBar to retrieve the CommandBar you are interested in.

For example:

private CommandBar FindCommandBar(Guid guidCmdGroup, uint menuID)

{

// Make sure the CommandBars collection is properly initialized, before we attempt to

// use the IVsProfferCommands service.

CommandBar menuBarCommandBar = ((CommandBars)_applicationObject.CommandBars)["MenuBar"];

// Retrieve IVsProfferComands via DTE's IOleServiceProvider interface

IOleServiceProvider sp = (IOleServiceProvider)_applicationObject;

Guid guidSvc = typeof(IVsProfferCommands).GUID);

Object objService;

sp.QueryService(ref guidSvc, ref guidSvc, out objService);

IVsProfferCommands vsProfferCmds = (IVsProfferCommands)objService;

return vsProfferCmds.FindCommandBar(IntPtr.Zero, ref guidCmdGroup, menuID) as CommandBar;

}

An example add-in using this code is can be found on in the GotDotNet Code Gallery as FindCommandBar.zip.

Happy Coding,
Dr. eX.

Using EnableVSIPLogging to identify menus and commands with VS 2005 + SP1

Dr. Ex — Tue, 17 Apr 2007 22:06:00 GMT

One of the most frequently asked questions related to Visual Studio Package and Add-in development concerns how to add additional menus and commands to a specific dropdown or context menu in the Visual Studio IDE.

Adding the menu or command is the easy part. Add-in developers typically use the Commands2.AddNamedCommand2 and Command.AddControl methods, and Visual Studio Package developers use a .CTC resource. In both instances, the hard part is trying to identify the menu or toolbar you actually want to add a new menu or command to.

The Problem:

Trying to identify a specific dropdown or popup menu can be a frustrating experience. Historically, add-in developers have resorted to experimenting with Visual Studio macros to try and discover the appropriate CommandBar name in order to successfully extract a specific CommandBar object from the environment’s DTE.CommandBars collection. Similarly, Visual Studio Package developers typically resort to searching the various .H and .CTC files included with the Visual Studio SDK. In both instances, success is not always guaranteed. Especially if the menu or toolbar you were interested in, was implemented by some package or add-in that was developed by a third party, or after the Visual Studio documentation and SDKs were released.

The Solution:

Visual Studio Package developers know that the various menus, toolbars and commands integrated into the Visual Studio IDE, are identified by a unique GUID:ID pair. However, what they may not be aware of is a new undocumented feature introduced with Visual Studio Service Pack 1, which displays this information on demand.

When the DWORD registry value below is set to 1, CTRL+SHIFT is pressed, and you attempt to display a menu or execute a command, a VSDebug Message dialog will be displayed containing the GUID and ID of that menu or command.

Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0\General]
"EnableVSIPLogging"=dword:00000001

(Hint #1, copy the above into an “EnableVSIPLogging.reg” file. And then dblclick the file to merge this value into the registry)

For example: Set the above registry value and restart the Visual Studio IDE. Then click on the File menu, press CTRL+SHIFT, then hover over the File.New menu item. This will result in the following dialog being displayed.

To display similar data for a specific command (menu item), click on the “Help” menu, press CTRL+SHIFT, and then select the “About Microsoft Visual Studio” menu item. This will result in the following dialog being displayed.

(Hint #2: Use CTRL+C to copy the text in the VSDebug dialog to the clipboard)

In both instances the Guid and CmdID are the values we are interested in, as this forms the GUID:ID pair that uniquely identifies the command or menu that was to be invoked.

For developers using the Visual Studio Automation model, the GUID:ID of the command can be used with the DTE.ExecuteCommand, and IVsProfferCommands.FindCommandBar methods. Additional details about using IVsProfferCommands.FindCommandBar can be found in the Dr. eX blog entry entitled "Using IVsProfferCommands to retrieve a Visual Studio CommandBar".

For developers authoring Visual Studio Packages, the GUID:ID pair displayed for command data, can be used to enable, disable, or hide existing commands from their IOleCommandTarget.QueryStatus implementations. And the GUID:ID pair for menu data, can be used to parent new commands, menu groups, and controls onto existing menus, via the .CTC resource.

Note, the GuidID, Type, and Flags are internal fields displayed by the VSDebug Message dialog, and are not relevant outside the Visual Studio development team. The NameLoc field is the localized name for the menu. The CanonicalName field is the dotted command name, used in the command window, DTE.ExecuteCommand, and in the KeyBindings dialog. And the LocalizedName field is the localized canonical name for the command.

Happy Coding,
Dr. eX

Visual Studio Extensibility Demystified

Dr. Ex — Thu, 16 Nov 2006 23:59:00 GMT

Since we have placed the VS 2005 SDK 3.0 on the Microsoft Download Center in September, we have seen a lot of developers downloading the SDK. The developers who are using the SDK now are no longer just developers who build commercial VSIP products. Users of the SDK now include students and developer enthusiasts who are building Visual Studio extensions to make their work more productive or just for fun and curiosity.

To that end, I'd like to spend a little bit of time explaining the various levels of Visual Studio extensibility to help developers who are new to the Visual Studio platform get ramped up.

Within the Visual Studio environment itself, there are 3 levels of extensibility: macros, add-ins and VSPackages.

Macros

Macros are the easiest way for developers to quickly gain access to Visual Studio's underlying automation object model. If you hit Alt+F11 in Visual Studio, the Macros IDE will appear in which you can start writing your macro. Macros are sometimes called the "duct tape" of Visual Studio because of its versatility and flexibility. You can easily combine Visual Studio commands or set automation properties to create interesting behaviors. For example, the following is a very simple macro that toggles the word wrap text editor option:


Sub ToggleWordWrap()

DTE.Properties("TextEditor", "Basic").Item("WordWrap").Value = _
Not DTE.Properties("TextEditor", "Basic").Item("WordWrap").Value 

DTE.Properties("TextEditor", "PlainText").Item("WordWrap").Value = _
Not DTE.Properties("TextEditor", "PlainText").Item("WordWrap").Value 

DTE.Properties("TextEditor", "CSharp").Item("WordWrap").Value = _
Not DTE.Properties("TextEditor", "CSharp").Item("WordWrap").Value 

DTE.Properties("TextEditor", "C/C++").Item("WordWrap").Value = _
Not DTE.Properties("TextEditor", "C/C++").Item("WordWrap").Value

End Sub

If you are interested in learning more about how to create, record and use macros, I would suggest that you go here for some resources.

So when should you use macros as the VS extensibility model? The scenarios that are great for using macros are those where you are trying "script" Visual Studio to automate certain tasks, provided that you can accept several limitations:

Macros can only be written in VB .NET.
To share macros with others, you must give them your macro projects which will include source code. Since the user of the macros can see the source code, there is no protection of your intellectual property.
Some extensibility scenarios cannot be achieved via macros. For example, you cannot create a new tool window, a new editor or a new project system via macros.

Scripting the IDE is powerful and often useful in many scenarios. But if you want to do more than "duct-taping", you will need to develop Add-ins or VSPackages.

Add-ins

Similar to macros, add-ins also leverage on the automation object model of Visual Studio. But unlike macros, add-ins are compiled into binary code so your intellectual property can be protected. Perhaps more importantly, add-ins allow you to seamlessly integrate new tool windows, plug in options pages, dynamically enable commands and add branding onto the splash screen & Help About boxes - scenarios that macros do not enable. Features offered by add-ins can fit seamlessly into the IDE as if they were a part of Visual Studio. In implementation, you also have the choice of creating add-ins in C#, VB .NET or C++.

There are many great add-ins in the community today. Visual Studio Hacks has a list of interesting add-ins here. James Avery has written a great MSDN article about the ten must-have tools (some of which are add-ins) for Visual Studio. A couple of student interns from the C# team has created some interesting add-ins that enhances code navigation and editing.

As you can see, add-ins can be used to build tools and features that support a large number of scenarios. The automation object model is extremely powerful. To get a sense of what this automation object model looks like, you can refer to the Automation Object Model chart here on MSDN. If you are interested in learning more about how to create add-ins, Creating Add-ins and Wizards is a great place to start on MSDN.

VSPackages

Now here comes the most powerful way to extend Visual Studio - VSPackages . Using VSPackages (a.k.a. VSIP interfaces), you gain access to the same API that internal teams at Microsoft have to integrate anything you want inside Visual Studio. This deep level of integration allows developers to build everything that add-ins enable, plus more. With VSPackages, you can even build custom project systems, debuggers, editors, data designer extensions and language integrations. IronPython is a great example of a language integration project built with VSPackages, and you can find this sample integration in the Visual Studio SDK.

By the way, the Visual Studio SDK is a great way to start learning about how to use this powerful mechanism to deeply integrate with Visual Studio. You can view the online documentation here. It is easy to get started with VSPackages once you have the SDK installed because it provides Wizards to help you create your first command, tool window or editor via VSPackages. In VS 2005, the Managed Package Framework has made VSPackage development a lot easier. But one thing that continues trip up a lot of developers when creating a VSPackage is the need for a Package Load Key (PLK). Normally, in order for a VSPackage to load, it needs to have a unique PLK that matches several pieces of information about the package. But on the VSPackage developer's machine, this is not needed because the Visual Studio SDK installs a developer key that allows all packages to load without PLKs. So while you are developing your VSPackage, it may work perfectly, and then when you deploy it to other machines, your VSPackage may fail to load.

What you need to do is to request a PLK through the VSIP member site. You need to register for an account (it's free!) before being able to request for a PLK, and you need to make sure the information you entered in PLK request process remains unchanged in your code. The PLK is generated based on the following pieces of information:

Company Name
Package GUID
Product Name
Product Version
Minimum Product Edition

If you change any of this information in your VSPackage, you will need to re-request a new PLK through the website. Next month, we will cover more about debugging package load failures.

Conclusion

Visual Studio is a great extensibility platform that offers developers many choices for how they want to customize and extend their development environment to meet their unique needs. Which one of macros, add-ins or VSPackages is right for you depends on your scenarios. In general, you can use these rule-of-thumbs:

If you are trying to do automate tasks in the IDE quickly and you are fine with distributing your code in source code form, macros maybe the most appropriate.
If you want to distribute your code in binary form, and the automation object model satisfy your needs, add-ins maybe the most appropriate.
If you want to create a custm project system, editor, debugger or language service, you will need to use VSPackages.

I hope that was helpful in demystifying VS Extensibility.

- Dr. Ex.