This documentation is archived and is not being maintained.

Commands::AddNamedCommand Method

Creates a named command that is saved by the environment and made available the next time the environment starts, even if the Add-in is not loaded on environment startup.

Namespace:  EnvDTE
Assembly:  EnvDTE (in EnvDTE.dll)

Command^ AddNamedCommand(
	[InAttribute] AddIn^ AddInInstance, 
	[InAttribute] String^ Name, 
	[InAttribute] String^ ButtonText, 
	[InAttribute] String^ Tooltip, 
	[InAttribute] bool MSOButton, 
	[InAttribute] int Bitmap, 
	[InAttribute] array<Object^>^% ContextUIGUIDs, 
	[InAttribute] int vsCommandDisabledFlagsValue


Type: EnvDTE::AddIn

Required. The AddIn Object is adding the new command.

Type: System::String

Required. The short form of the name for your new command. AddNamedCommand uses the preface, Addins.Progid., to create a unique name.

Type: System::String

Required. The name to use if the command is bound to a button that is displayed by name rather than by icon.

Type: System::String

Required. The text displayed when a user hovers the mouse pointer over any control bound to the new command.

Type: System::Boolean

Required. Indicates whether the named command's button picture is an Office picture. True = button. If MSOButton is False, then Bitmap is the ID of a 16x16 bitmap resource (but not an icon resource) in a Visual C++ resource DLL that must reside in a folder with the language's locale identifier (1033 for English).

Type: System::Int32

Optional. The ID of a bitmap to display on the button.

Type: array<System::Object>%

Optional. A SafeArray of GUIDs that determines which environment contexts (that is, debug mode, design mode, and so on) enable the command. See DisableFlags.

Type: System::Int32

Optional. Determines whether the disabled state of the command is invisible or grey when you supply a ContextUIGUIDs and none are currently active.

Return Value

Type: EnvDTE::Command
A Command object.

Add-ins can later change the ButtonText name by responding to the QueryStatus method. If the text begins with "#", then the rest of the string is an integer that represents a resource ID in the Add-in's registered satellite DLL.

ppsaContextUIGUIDs is used when the Add-in is not loaded and thus cannot respond to the QueryStatus method. If ppsaContextUIGUIDs is empty, then the command is enabled until the Add-in is loaded and can respond to QueryStatus.

The Add-in can receive invocation notification through the IDTCommandTarget interface. A button can be added by using the OnConnection method of the IDTExtensibility2 interface

' Macro code.
Imports Microsoft.VisualStudio.CommandBars
Sub AddControlExample()
   ' Before running, you must add a reference to the Office 
   ' typelib to gain access to the CommandBar object. Also, for this 
   ' example to work correctly, there should be an add-in available 
   ' in the Visual Studio environment.
   Dim cmds As Commands
   Dim cmdobj As Command
   Dim cmdbarobj As CommandBar
   Dim colAddins As AddIns

   ' Set references.
   colAddins = DTE.AddIns()
   cmds = DTE.Commands
   cmdobj = cmds.Item("File.NewFile")

   ' Create a toolbar and add the File.NewFile command to it.
   cmds.AddCommandBar("Mycmdbar", _
   MsgBox("Commandbar name: " & cmdbarobj.Name)
   cmds.AddNamedCommand(colAddins.Item(1), "MyCommand", _
   "Button Text", "Some tooltip", True)
End Sub