Commands2.AddNamedCommand2 Method
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Caution
AddIn related extension points are no longer supported in Visual Studio.
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.
EnvDTE::Command AddNamedCommand2(EnvDTE::AddIn const & AddInInstance, std::wstring const & Name, std::wstring const & ButtonText, std::wstring const & Tooltip, bool MSOButton, winrt::Windows::Foundation::IInspectable const & Bitmap, std::Array <winrt::Windows::Foundation::IInspectable const &> const & & ContextUIGUIDs, int vsCommandStatusValue = 3, int CommandStyleFlags = 3, EnvDTE80::vsCommandControlType ControlType = EnvDTE80.vsCommandControlType.vsCommandControlTypeButton);
[System.Runtime.InteropServices.DispId(20)]
public EnvDTE.Command AddNamedCommand2 (EnvDTE.AddIn AddInInstance, string Name, string ButtonText, string Tooltip, bool MSOButton, object Bitmap, ref object[] ContextUIGUIDs, int vsCommandStatusValue = 3, int CommandStyleFlags = 3, EnvDTE80.vsCommandControlType ControlType = EnvDTE80.vsCommandControlType.vsCommandControlTypeButton);
[System.Runtime.InteropServices.DispId(20)]
[System.Obsolete("AddIn related extension points are no longer supported in Visual Studio.")]
public EnvDTE.Command AddNamedCommand2 (EnvDTE.AddIn AddInInstance, string Name, string ButtonText, string Tooltip, bool MSOButton, object Bitmap, ref object[] ContextUIGUIDs, int vsCommandStatusValue = 3, int CommandStyleFlags = 3, EnvDTE80.vsCommandControlType ControlType = EnvDTE80.vsCommandControlType.vsCommandControlTypeButton);
[<System.Runtime.InteropServices.DispId(20)>]
abstract member AddNamedCommand2 : EnvDTE.AddIn * string * string * string * bool * obj * Object[] * int * int * EnvDTE80.vsCommandControlType -> EnvDTE.Command
[<System.Runtime.InteropServices.DispId(20)>]
[<System.Obsolete("AddIn related extension points are no longer supported in Visual Studio.")>]
abstract member AddNamedCommand2 : EnvDTE.AddIn * string * string * string * bool * obj * Object[] * int * int * EnvDTE80.vsCommandControlType -> EnvDTE.Command
Public Function AddNamedCommand2 (AddInInstance As AddIn, Name As String, ButtonText As String, Tooltip As String, MSOButton As Boolean, Optional Bitmap As Object, Optional ByRef ContextUIGUIDs As Object(), Optional vsCommandStatusValue As Integer = 3, Optional CommandStyleFlags As Integer = 3, Optional ControlType As vsCommandControlType = EnvDTE80.vsCommandControlType.vsCommandControlTypeButton) As Command
- Name
- String
Required. The short form of the name for your new command. AddNamedCommand2(AddIn, String, String, String, Boolean, Object, Object[], Int32, Int32, vsCommandControlType) uses the preface Addins.Progid. to create a unique name.
- ButtonText
- String
Required. The name to show in the UI for this command.
- Tooltip
- String
Required. The text displayed when a user hovers the mouse pointer over any control bound to the new command.
- MSOButton
- Boolean
Required. Must be false
.
- Bitmap
- Object
Optional. The ID of a bitmap to display on the button.
Bitmap
can be one of the following:
- A Bitmap
- An Icon
- An IPicture
- The ID of a 16x16 bitmap resource (but not an icon resource) that is provided by the add-in. Visual Studio looks first in the add-in's satellite DLL. If the resource is not found there, the add-in DLL will be searched.
- ContextUIGUIDs
- Object[]
Optional. The GUIDs that determine which environment contexts (that is, debug mode, design mode, and so on) show the command.
- vsCommandStatusValue
- Int32
Optional. Determines whether the disabled state of the command is invisible or disabled when you supply a ContextUIGUIDs
parameter and none are currently active. See vsCommandDisabledFlags.
- CommandStyleFlags
- Int32
Optional. One of the vsCommandStyle flags, in particular vsCommandStylePict, vsCommandStylePictAndText, or vsCommandStyleText.
- ControlType
- vsCommandControlType
Optional. Defines the control type added when the UI is created.
The named command that was created.
- Attributes
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.
There are two default command states: the default enabled state and the default visibility state. These default states are important if a command handler cannot be found (because the component isn't loaded or doesn't implement IDTCommandTarget). If your component is loaded and implements IDTCommandTarget, the default values never apply.
There are two interesting cases where default states are used:
You provide UI context GUIDs via the
ContextUIGUIDs
parameter. In this case visibility is entirely determined by the supplied context GUIDS. If the context is active, then your command is visible, otherwise it is hidden. Enabled state is entirely determined by the default values. By default in Visual Studio a command is always enabled if you pass vsCommandDisabledFlagsGrey then your default state will be disabled. If you pass vsCommandDisabledFlagsEnabled, or you simply don't supply this parameter, then your default state is enabled.You do not provide UI context GUIDs via the
ContextUIGUIDs
parameter. In this case visibility is based on the flags you pass tovsCommandStatusValue
or the default state. Default command visibility in VS is to be visible. If you pass vsCommandDisabledFlagsHidden here, the default is invisible. Enabled state is the same here as it is in case 1 above (determined by the flags and/or default VS behavior).
The addin can receive invocation notification through the IDTCommandTarget interface. A button can be added by using the OnConnection method of the IDTExtensibility2 interface.