IVsUIHierarchy.ExecCommand Method

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

Executes a command on a specific item within a UI hierarchy window, or on the hierarchy itself.

public:
 int ExecCommand(System::UInt32 itemid, Guid % pguidCmdGroup, System::UInt32 nCmdID, System::UInt32 nCmdexecopt, IntPtr pvaIn, IntPtr pvaOut);

public int ExecCommand (uint itemid, ref Guid pguidCmdGroup, uint nCmdID, uint nCmdexecopt, IntPtr pvaIn, IntPtr pvaOut);

abstract member ExecCommand : uint32 * Guid * uint32 * uint32 * nativeint * nativeint -> int

Public Function ExecCommand (itemid As UInteger, ByRef pguidCmdGroup As Guid, nCmdID As UInteger, nCmdexecopt As UInteger, pvaIn As IntPtr, pvaOut As IntPtr) As Integer

Parameters

itemid

UInt32

[in] Identifier of the item affected by the command passed to IVsUIHierarchy. For a list of itemid values, see VSITEMID. For single selection, this value is the actual item ID. For multiple selections, set itemid equal to VSITEMID_SELECTION.

pguidCmdGroup

Guid

[in, unique] Unique identifier of the command group; can be null to specify the standard group. All the commands that are passed in the nCmdID must belong to the group specified by pguidCmdGroup

nCmdID

UInt32

[in] The command to be executed. This command must belong to the group specified with pguidCmdGroup.

nCmdexecopt

UInt32

[in] Values describe how the object should execute the command.[1|1] nCmdexecopt value[1|2] Value[1|3] Description[2|1] OLECMDEXECOPT_DODEFAULT[2|2] 0[2|3] Prompt the user for input or not, depending on the default behavior[3|1] OLECMDEXECOPT_PROMPTUSER[3|2] 1[3|3] Execute the command after obtaining user input.[4|1] OLECMDEXECOPT_DONTPROMPTUSER[4|2] 2[4|3] Execute the command without prompting the user. For example, clicking the Print toolbar button causes a document to be immediately printed without user input. [5|1] OLECMDEXECOPT_SHOWHELP[5|2] 3[5|3] Show help for the corresponding command, but do not execute.

pvaIn

IntPtr

nativeint

[in, unique] Pointer to a VARIANTARG structure containing input arguments. Can be null.

pvaOut

IntPtr

nativeint

[in, out, unique] VARIANTARG structure to receive command output. Can be null.

Returns

Int32

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsUIHierarchy::ExecCommand(  
   [in] VSITEMID itemid,  
   [in, unique] const GUID * pguidCmdGroup,  
   [in] DWORD nCmdID,  
   [in] DWORD nCmdexecopt,  
   [in, unique] VARIANT * pvaIn,  
   [in, out, unique]VARIANT* pvaOut  
);  

This method is similar to the Exec method, except that the Exec method does not support hierarchies, whereas the IVsUIHierarchy.ExecCommand method includes the itemid parameter, which identifies the hierarchy item to which the command applies.

The environment executes IVsUIHierarchy.ExecCommand when the UI hierarchy window has focus. The UI hierarchy window delegates all menu or toolbar commands to the UIHierarchy object that is the common parent for the selection. This provides the UIHierarchy object the option to handle commands that only apply when the UI hierarchy window has focus. Examples include the Delete and Remove commands. These commands must not be handled through Exec. The IOleCommandTarget of the active project is included in the usual command routing of the environment, even when another window (for example, a document window) has focus. To handle Delete and Remove for a project, use IVsHierarchyDeleteHandler.

If the UI hierarchy window is not the active window, but it is still the active hierarchy, meaning that it is the last hierarchy to have been selected, then any commands that involve the active hierarchy are sent through the IOleCommandTarget interface instead of the IVsUIHierarchy interface. For example, if the selection is changed from the Solution Explorer to the task list, then the Solution Explorer is the active hierarchy, but the active window is the task list. In this case, any commands that are related to the active hierarchy, such as adding an item to the project, are sent through the IOleCommandTarget interface.

Commands like adding a project item should not be handled by the IVsUIHierarchy methods because they will not be available from outside of the hierarchy window. Only use IVsUIHierarchy to handle commands that require the UI Hierarchy window to have focus, or that act on a specific item within the hierarchy.

The command group VSConstants.VsUIHierarchyWindowCmdIds is used to handle direct UI manipulations in the UI hierarchy window.

VSHPROPID_EditLabel must be supported in GetProperty and SetProperty for item name editing to be enabled.

The following standard commands should only be handled using the IVsUIHierarchy interface:

// {5efc7975-14bc-11cf-9b2b-00aa00573819}

DEFINE_GUID(CLSID_StandardCommandSet97, 0x5efc7975, 0x14bc, 0x11cf, 0x9b, 0x2b, 0x00, 0xaa, 0x00, 0x57, 0x38, 0x19);

#define cmdidCopy 15

#define cmdidCut 16

#define cmdidDelete 17

#define cmdidPaste 26

#define cmdidRemove 168

#define cmdidRename 150