Here are some previous posts which (briefly) describe the domain:

http://blogs.rev-net.com/ddewinter/2008/02/16/the-linq-to-sql-model/

http://blogs.rev-net.com/ddewinter/2008/02/16/linq-to-sql-and-database-schema-sync/

Any ideas about directions for the tool? Or maybe something that wasn’t covered in the screencast? I’d love to hear your ideas.

• Part 1 – Discusses UI Contexts and how to utilize the built-in ones for dynamic menu commands.
• Part 2 – Discusses the use of the BeforyQueryStatus event to provide more flexibility than built-in UI contexts.

What we’ve explored to date is a way to provide dynamic menu commands (e.g. dynamic visibility, enabled state) in our own package, and the techniques that I’ve shown thus far have worked well for this scenario. However, if you want to develop multiple menu commands or even multiple packages that rely on a custom condition (as shown in Part 2), then you’re stuck implementing the same logic in an event handler for the BeforeQueryStatus event for each OleMenuCommand.

Wouldn’t it be great if we could create our own UI Context, similar to the built-in ones like UIContext_NoSolution or UIContext_FullScreenMode? That way we can create multiple menu commands that rely on that context or even multiple packages which rely on it.

And that’s exactly what this post will cover. We’ll use the solution starting from where we left off at the end of Part 2.

Step 1: Creating New Commands

Because Part 2 covered how to create a new menu command from scratch using the VSCT file and the appropriate procedural code, I’m not going to cover the process in depth here. I’ll be creating two new menu commands, which will be part of the command set that we created in Part 2 (guidDynamicMenuDevelopmentCmdSetPart2 in the GuidList class). In the snippets that follow, the bold sections indicate what I added to achieve this:

PkgCmdIDList Class (in PkgCmdID.cs)

DynamicMenuDevelopment.vsct File – Symbols Element

DynamicMenuDevelopment.vsct File – Buttons Element

In summary, I added two IDs to the PkgCmdIDList class which specify the IDs of the two new menu commands I’m going to add. Furthermore, I registered these IDs in the VSCT file using IDSymbol elements in the guidDynamicMenuDevelopmentCmdSetPart2 GuidSymbol (which I mentioned earlier). Finally, I added two buttons to the Buttons element that map directly to the commands we created. At this point, we could create handlers for these commands, but it’s really not necessary for us to achieve what we want. If you press F5 and open a project that has at least one project item in it, you’ll see our two new menu commands when right clicking on a project item:

(These menu commands appear in the Solution Explorer because we defined their parents as being in the Solution Explorer context menu—see Post 2 for details.)

Step 2: Implementing the Custom UI Context

For our custom UI context, let’s re-implement the functionality that the second command we created (in Post 2) did—display itself when a .dbml file is selected in the Solution Explorer but hide itself when anything else is selected. To do this we’ll need a way to tell Visual Studio what the current UI Context is. Fortunately, the SVsShellMonitorSelection service, through the IVsMonitorSelection interface, exposes the functionality to get and set the current UI context (as well as means to track the current selection). This will definitely fit our needs, but how do we receive notifications when the current selection changes?

This is where the IVsSelectionEvents interface really comes in handy. It doesn’t correspond to a specific Visual Studio service; instead, it’s used in tandem with the IVsMonitorSelection interface to receive notifications when the UI context has changed, when the current selection has changed, and when an element value has changed. The last notification is outside of the scope of this article, but this blog post may help you understand its purpose.

Is what we must do becoming clearer to you? If not, maybe the following steps will help:

1. Create a UI context GUID that we can use for DBML file selection.
2. Implement the IVsSelectionEvents interface.
3. Use that implementation with the SVsShellMonitorSelection service to listen for selection events.
4. When the selection changes to a DBML file, set the UI context that we created in Step 1 as the active UI context.
5. Of course, the final step is to hook up our
   menu commands to this UI context to test our work.

Creating the UI Context GUID

This is probably the easiest step out of the five, as all it does is involve our creating a new GUID to put in the GuidList class that we can reference later. I’ll do this using guidgen.exe, accessible through the Tools > Create GUID option in Visual Studio. The result looks like this:

Implementing the IVsSelectionEvents Interface

This interface is fairly straightforward to implement. Before getting into the code, remember that we are checking what the new selection is when it changes. If it’s a DBML file in the Solution Explorer, then we activate our UI context. Here’s what my implementation looks like:

The implementation should make sense based off my previous article. When the selection changes, we inspect the new IVsHierarchy to find its selection. If the name of the selection ends with “.dbml”, then we are dealing with a DBML file. We activate the UI context in this case, and deactivate it in all other cases. Before any of that happens, though, we have to register the UI context GUID with the SVsShellMonitorSelection service, which is what the RegisterContext() method does. The cookie that we receive from the call to IVsMonitorSelection.GetCmdUIContextCookie() is then used to set the UI context later on. There’s a bit of a trickery involved here to understand what’s going on, but most of it should be self-evident.

Registering the Selection Event Listener

Now that we have a listener for the selection events, we need to register it with the selection service. To do this, add this to the Initialize() method in our package:

Here, mySelectionEvents and mySelectionEventsCookie are private fields in the package class. The only unfamiliar territory is the IVsMonitorSelection.AdviseSelectionEvents method. Now, I am by no means a COM expert, but this pattern of advising for events and then unadvising for them later on seems to be a common task for applications that interact with COM. The fact that we can unadvise for the events implies that there is a unique identifier for an “advise.” This unique identifier is the cookie that is passed by reference into the call for advising for selection events. We store this value in a private field so we can unadvise at an appropriate time i.e. in the package’s Dispose method:

Hooking Up the Menu Commands

It’s been a long toll, but we’re almost to the end! The last step is to hook up our two menu commands to the UI context we created. Part 1 shows how to do this with built-in UI contexts, and doing it with a custom one is no different. The first step is to add the GUID for our custom UI context to the Symbols element. Then, we add VisibilityItem elements to the VisibilityConstraints section which hook up the menu commands to that context.

The GUID Symbol for the Custom UI Context

The Visibility Constraints

Step 3: The Results!

Now that we’ve gone through that rigmarole, press F5 and load a project with a DBML file in it (or create a DBML file in some file). You’ll see that our two new menu commands (as well the menu command we implemented with the BeforeQueryStatus event handler in Part 2) show up only when right clicking on a DBML file.

This concludes both this article on building custom UI contexts and this series on dynamic menus in Visual Studio. I hope this and the past articles help in you Visual Studio Package development!

Associated Solution

Other Articles in the Series

• Part 1 – Using UI Contexts
• Part 2 – The BeforeQueryStatus Event

The picture above illustrates the basic structure when the power toy analyzes Visual Studio itself. Because of how many commands there are in Visual Studio, it would be overwhelming to show them all in the image, so it may be more helpful to look at the command table for a specific package or VSCT file. If you’ve been reading this blog you can probably infer that my “favorite” package is the LINQ to SQL package, so let’s have at some more features of the tool with it. (For reference, from your Visual Studio 2008 install directory, it is in Common7IDEMicrosoft.VisualStudio.ORDesigner.DslPackage.dll.) Simply opening the DLL in the power toy gives us the following:

As you can see, we can drill down into the menus exposed by the VSCT file embedded in the LINQ to SQL package assembly. Although small compared to the rest of Visual Studio, packages like these can really help you become familiar with the taxonomy of groups, menus, buttons, etc. that are involved in a command table. Another advantage is that it shows you the snippet of the file you have highlighted in the treeview. For example, since we highlighted the Association button in the picture above, a contextual snippet window below will show the following:

And there it is, as specified in the original VSCT file. I am not sure about whether snippets from other files in their respective formats, or whether they show in a VSCT format like this one. Regardless, this functionality can be a great aid to package developers looking for an easy way to find their desired hooks within Visual Studio. Give this tool and try and be sure to check out the document (linked on this page) for more features!

If you remember from last time, we were able to create a dynamic menu command without any lines of procedural code (other than those generated by the wizard). The result was a menu command that showed itself only when no solution was loaded in Visual Studio. Immediately a solution was loaded, the menu command disappeared. The limitations of this approach are that you’re reliant on built-in UI contexts, such as UICONTEXT_NoSolution. However, what I needed for my DBML Fixup project was a way to add menu commands when right clicking on .dbml files (LINQ to SQL Classes) in the Solution Explorer. The built-in UI contexts that we reviewed in the previous post are not enough to give us this functionality. In this tutorial, I take you through step-by-step on how to add this feature to your VS packages. We have to do a bit of digging though, so let’s get started!

The first thing we need to do is to create a new a menu command using our existing solution. Because we don’t have the wizard to help us this time, we’ll have to create our menu command from scratch.

Step 1: Creating the New Command

Our first step is to create the GUID:ID pair that Visual Studio will use to identify our new menu command. The GUID represents a set of commands (or command set) exposed by this package; one of these was created by the package wizard when the solution was generated. However, for this part of the tutorial, we’ll go ahead and create a new command set in the Guids.cs file. (We can get a new GUID from the Tools > Create GUID menu item.) Afterwards, my Guids.cs file looks like this:

Pardon the unoriginal name of "CmdSetPart2." The next step is to add an ID that maps to the specific menu command we are going to add. This can be changed in the PkgCmdID.cs file in our project. Here I will add the cmdidQueryStatusCommand with a value of 257:

So that was fairly simple, but obviously we haven’t registered it with Visual Studio, so there’s no way the Visual Studio shell will know about this menu command. To do so, we need to make some amendments to the .vsct file. The first of these changes is to identify the new menu command GUID and ID pair in the Symbols section, so that we can reference it elsewhere. This is also easy to do and requires a few lines of XML, which can be added as any first-level child of the Symbols node:

As you can see, this information is based directly off the two previous steps. The "guidDynamicMenuDevelopmentCmdSetPart2" command set has the same GUID as in our GuidList class, and the "cmdidQueryStatus" menu command ID has the same value as in the PkgCmdIDList class.

Our objective is to show this menu command when we right click on DBML files in the designer; this means we’ll need to create a new Group element whose parent is the Solution Explorer’s context menu. Then we’ll need to create a Button element to put in that Group, which represents the menu command itself. This doesn’t seem like such a problem, until you try to define the Group’s parent…

What goes in the place of the question marks? Well, we might be able to find it in one of the copious header files that sits in the Visual Studio SDK’s VisualStudioIntegrationCommonInc directory, but I’m willing to bet that there’s a faster way. And it turns out there is. Looking at Dr. eX’s blog entry on VSIPLogging reveals that a simple registry key will allow you see to the GUID:ID pair of almost any menu command in Visual Studio, including those developed by third parties. Changing this setting in the registry and relaunching Visual Studio allows us to check what the GUID and the ID we need are; as it turns out, holding the Ctrl+Shift keys down and right clicking on a project item in the Solution Explorer gives us the information we need:

We can use this information to fill in the Parent’s details, but we’ll need to register the GUID and CmdID in the GuidSymbols element in our .vsct file first.

The Button element isn’t too exciting by comparison; in fact it doesn’t differ much from the Button element from the last tutorial. I include it here for reference:

OK, that’s it for the .vsct edits. Notice that our Button element still has the "DynamicVisibility" flag, but we have not specified a visibility constraint; this is because we will handle the changes ourselves in procedural code. The final thing we have to do to finish the "plumbing" work by creating our menu command and an event handler to handle its invocation. I’ll add this code in the DynamicMenuDevelopmentPackage.cs file in the Initialize method. If you navigate there, you’ll see the wizard-generated code for the first menu command. It’s only a few lines of code to hook everything together with our second menu command:

One thing to note here is that in contrast to the first menu command, we are creating an OleMenuCommand, not a regular MenuCommand. The reasons will become apparent later, but for now, let’s press F5 to see what we’ve got. Open an existing solution (or create a new one if it’s easier to do so) and right click on a project item (not a folder, project, or solution node, though) and you will see our "Query Status" command:

Step 2: Making It Dynamic

As expected, though, it shows up regardless of the selected item in the project, so we haven’t reached the end yet! Going back to the code in DynamicMenuDevelopmentPackage, we discover a use for the OleMenuCommand vs. the MenuCommand. The OleMenuCommand exposes an event called BeforeQueryStatus, which is raised right before Visual Studio asks what the state of a particular menu item is. In this case, it’s a perfect place to edit the state of our menu command based on the current selection in the Solution Explorer. Adding the following event handler to the BeforeQueryStatus event of that OleMenuCommand helps us achieve our desired goal:

I won’t explain all the code here, but the gist is that we are getting the name of the current selection, checking if it ends with the ".dbml" extension, and dynamically setting the visibility on our menu command based on that result. Unfortunately, this is still not enough to correctly implement our dynamic menu command, due to the fact that Visual Studio loads packages on demand. To make a long story short, the code that we just wrote to handle dynamic menu item visibility will be called only when the package is loaded, and the package is loaded only when some UI element exposed by the package is clicked, which invokes some piece of code in the underlying package. This does not really help us when all the package exposes is two menu commands!

This is a problem that I encountered recently, and consequently I am open to any suggestions. My solution has been to put the ProvideAutoLoadAttribute on the class, which tells Visual Studio to load the package automatically when it encounters a certain UI context. In this circumstance, the context "UICONTEXT_SolutionExists" (defined in vsshlids.h) suits our purposes perfectly. We’ll have to specify the GUID itself instead of its alias, however, like this:

And that’s it! Press F5 and open a solution to see for yourself. The "Query Status" command will appear only when right-clicking on .dbml files in the Solution Explorer.

Associated Solution

Other Articles in the Series

• Part 1 – Using UI Contexts
• Part 3 – Custom UI Contexts

In this series of posts I’m going to focus on three ways to make menu commands dynamic—that is, how to make menu commands invisible or disabled in certain contexts, but visible and enabled in others. Two of these ways I found through some experimentation. Consequently, I’m not sure whether these represent VSX best practices, so if anyone has any more input, it would be greatly appreciated. With that said, let’s get started.

Using a Built-In UI Context

For each of these techniques, I’ll be using the same solution, and I’ll post the solution with the current progress at the end of each post. But…first things first: create a new project and select the Visual Studio Integration Package project type.

The Visual Studio Integration Package Wizard pops up. For this tutorial we’ll use Visual C# and generate a new key file to sign the assembly.

For the basic information page, feel free to type whatever you want for the company name, package name, and detailed information. I’ll leave the minimum Visual Studio edition at "Standard," as well. On the next page, check the Menu Command check box to indicate to the wizard that we want to, of course, make a menu command.

We’ll provide the following command name and ID for the command the wizard will generate:

On the last page, uncheck the Integration Test Project and Unit Test Project options, as we won’t need these for this demonstration. If you are interested in the Integration Test and Unit Test options, have a look at this blog entry. Click "Finish," and the wizard will create the majority of the solution for us. Press F5 and verify that a "Built In UI Context" menu item appears in the Tools menu:

The integration package wizard has gotten us this far, but we have to supply the finishing touches in order to make this menu item dynamic. In order to do this we need a little background in the .vsct file’s structure. There should be one in your project (DynamicMenuDevelopment.vsct in my case). Go ahead and open that file. The following will briefly touch on the different points of the .vsct file. If you don’t have any previous experience working with these, please read this excellent post before continuing.

In the VSCT file, our menu command is represented by the sole Button element:

That "button" is parented by the "MyMenuGroup" group element:

And that group is parented by the Tools menu. If we look at the GuidSymbols element in the file, we can see the GUIDs for our package, guidDynamicMenuDevelopmentPkg, as well as our set of commands, guidDynamicMenuDevelopmentCmdSet. The latter has some IDs which identify the single menu command and the group: cmdidBuiltInUIContext and MyMenuGroup, respectively. But if you look at the Group’s parent in the previous XML snippet, you’ll see a GUID guidSHLMainMenu and an ID IDM_VS_MENU_TOOLS which are not defined here. Where do they come from? They are defined externally in the vsshlids.h, which we "imported" using one of the Extern elements at the beginning of the document.

From here, it’s very simple to add dynamic visibility. Navigate back to the Button element and add the CommandFlag element, as demonstrated below:

Simple, right? We’ve told Visual Studio that this command may be invisible at times and visible at other times, but we haven’t told it when. To do that, we must add a VisibilityConstraints element underneath the closing Commands tag.

If you think about it, you can make some educated guesses about what this piece of the XML says. The VisibilityItem element specifies the same GUID and ID pair as our Button element above, so they must be related. Furthermore, the element specifies a context attribute which we have not seen before. This is the sole part of the VSCT file that tells Visual Studio when a particular command is visible or invisible. You can also infer that UICONTEXT_NoSolution means that the menu command will be visible only when there is no solution open. Press F5 and try it!

That leaves one last question before wrapping up this technique, and that is "Where is UICONTEXT_NoSolution defined?" It certainly isn’t in our GuidSymbols, but if you remember we have a couple of external header files that we reference. One of those is vsshlids.h. If you navigate to the %PROGRAMFILES%Microsoft Visual Studio 2008 SDKVisualStudioIntegrationCommonInc directory, you’ll find vsshlids.h among a multitude of other header files. If you open that file and search for "UICONTEXT_", you’ll see a couple of different contexts, including UICONTEXT_NoSolution. You can use any of the other UI Contexts in this file in order to control dynamic visibility for your menu command.

That was pretty good for writing only a few lines of XML, but if there’s no built-in UI context that fits your requirements, then this solution will not work for you. Also, this technique works only for hiding and show menu commands, not for disabling and enabling them. In short, while it’s fairly easy to do, it’s sometimes not flexible enough for the job.

Next time I’ll outline another technique, which is also fairly simple, but requires us to write some code. Hope this helps you in your VSX development!

Edit: I realize I forgot to post the solution for this example! It is a Visual Studio 2008 solution and it’s located here.

Other Articles in the Series

• Part 2 – The BeforeQueryStatus Event
• Part 3 – Custom UI Contexts