Command Routing Algorithm
The Visual Studio command routing architecture makes it possible for commands to be handled by different VSPackages. To accomplish this, commands route systematically from the innermost (based on current selection) to the outermost (global) command context. For more information on this process, see How the Availability of Commands is Determined by IDE Context.
Order of Command Resolution
If a command has not been handled by any active command context upon reaching the global context, the environment loads the appropriate command-handling VSPackage to access the command.
Commands poll sequentially in ascending order through the following levels of command context:
Add-ins: The environment first offers the command to any add-ins that are present.
Shortcut menu: When a command is routed from a shortcut menu, it is first offered to the command target provided to the shortcut menu, and then to the normal routing.
If you want to bring up a shortcut menu, you must use the ShowContextMenu method. The environment passes a IOleComponentUIManager object to the document view object supporting the IOleInPlaceComponent interface. If you are not given a IOleComponentUIManager object and you want to bring up a shortcut menu, you must access the global SOleComponentUIManager service by calling the QueryService method on the environment's global service provider. Shortcut menus on hierarchies work the same way.
Focus window: The focus window is the currently selected window. This can be either a tool window or a document window.
Tool Window. A properly implemented tool window has an IOleCommandTarget interface which the environment can obtain by calling the QueryInterface method on the tool window pane, typically IVsWindowPane. The environment calls your command target when your tool window is the active window. However, if the tool window with focus is the Project window, then the command is routed to the IVsUIHierarchy interface that is the common parent of the selected items. If this selection spans multiple projects, the command routes to the SVsSolution hierarchy. The IVsUIHierarchy interface has the QueryStatusCommand and ExecCommand methods that are analogous to the corresponding commands on the IOleCommandTarget interface.
Document Window. To obtain an IOleCommandTarget interface from a document window, the environment must call the QueryInterface method on the document view object—either an instance of an IVsWindowPane interface or an instance of a document object (typically an IVsTextLines or IVsTextBuffer interface). If the document view object does not support the command, the environment executes the QueryInterface method on the document data object and routes the command to the IOleCommandTarget interface that is returned (this is an optional interface for document data objects).
Note
To properly activate a window and to ensure that command routing is updated, you must call the Show method on the component to make it the focus window.
Current project: The current project is the project that owns the active document window or the hierarchy with selection in Solution Explorer. The environment calls the QueryInterface method on the project to obtain the IOleCommandTarget interface that is implemented on the current, or active, hierarchy. The hierarchy should support commands that are valid whenever the hierarchy is active—even if a document window of a project item has focus. However, commands that apply only when Solution Explorer has focus must be supported with the IVsUIHierarchy interface and its QueryStatusCommand and ExecCommandmethods.
Cut, Copy, Paste, Delete, Rename, Enter, and DoubleClick commands require special handling. For information on handling Delete and Remove commands within hierarchies, see the IVsHierarchyDeleteHandler interface.
Environment: Each VSPackage should implement a command target that the environment can retrieve using the QueryInterface method. This command target handles any commands that are defined by its VSPackage.
Global: For commands that are not handled by the previously mentioned contexts, the environment attempts to route to the appropriate VSPackage that implements the IOleCommandTarget interface. For the QueryStatus method, the command's default flags are used if the VSPackage is not already loaded. For the Exec method, the VSPackage is loaded if it has not already been loaded.