Introducción a menús y barras de herramientas

Los menús y las barras de herramientas son la forma en que los usuarios acceden a los comandos de la extensión. Son formas gráficas cómodas de presentar los comandos a los usuarios. Normalmente, los comandos relacionados se agrupan en clústeres en el mismo menú o en la misma barra de herramientas.

Trabajar con menús y barras de herramientas

En esta introducción se describen estos principales escenarios para trabajar con menús y barras de herramientas:

• Crear un menú
• Colocar elementos en un menú
• Crear una barra de herramientas
• Colocar elementos en una barra de herramientas
• Creación de un grupo
• Colocar elementos en un grupo
• Colocar grupos en un menú o barra de herramientas
• Ordenación de selección de ubicación (prioridad)

Crear un menú

Para crear un menú con el nuevo modelo de extensibilidad, agregue una propiedad estática MenuConfiguration , adornando la clase con el VisualStudioContribution atributo . Esta propiedad estática se puede colocar en cualquier clase del proyecto de extensión. En los nuevos ejemplos del modelo de extensibilidad, existen en la Extension clase para simplificar. Los menús sin elementos secundarios visibles no estarán visibles en la interfaz de usuario.

[VisualStudioContribution]
public class ExtensionEntrypoint : Extension
{
  [VisualStudioContribution]
  public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%");
}

Clase MenuConfiguration

La MenuConfiguration clase tiene algunos parámetros con los que debe familiarizarse:

Parámetro	Type	Obligatorio	Descripción
DisplayName	Cadena	Sí	Nombre para mostrar predeterminado del menú. Rodea esta cadena con el carácter '%' para habilitar la localización de esta cadena. Consulte la sección Localización de metadatos.
TooltipText	Cadena	No	Texto que se va a mostrar como la información sobre herramientas cuando el menú se mantiene o se centra. Rodea esta cadena con el carácter '%' para habilitar la localización de esta cadena. Consulte la sección Localización de metadatos.
Colocaciones	CommandPlacement[]	No	Especifica los grupos existentes en Visual Studio a los que se asignará el menú primario. Consulte en Colocar un menú en el IDE.
Children	MenuChild[]	No	Describe el conjunto de comandos, menús y grupos que deben estar primarios en este menú. El orden en que se definen estos elementos en la matriz representa el orden en que aparecerán visualmente en el IDE. Ver en Colocar elementos en un menú

Colocar un menú en el IDE

Los menús se colocan en el IDE de la misma manera que los comandos. Consulte Colocar un comando en el IDE.

public override MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Placements = new CommandPlacement[]
    {
        CommandPlacement.KnownPlacements.ToolsMenu
    },
};

Colocar elementos en un menú

La colocación en el elemento de un menú se realiza agregando elementos a la Children matriz en .MenuConfiguration El orden en que se agregan elementos a esta matriz determina cómo se mostrarán visualmente estos elementos en el IDE.

Colocar comandos en un menú

La colocación de comandos en un menú se realiza mediante el MenuChild.Command<T> método , reemplazando el argumento de plantilla por el nombre de clase de Command.

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Command<MyCommand>(),
    },
};

Colocar menús en un menú

La colocación de menús en un menú se realiza mediante el MenuChild.Menu método , pasando otro MenuConfiguration como parámetro.

[VisualStudioContribution]
public static MenuConfiguration MyChildMenu => new("My Child Menu!");

[VisualStudioContribution]
public static MenuConfiguration MyParentMenu => new("My Parent Menu!")
{
    Children = new[]
    {
        MenuChild.Menu(MyChildMenu),
    },
};

Separación de elementos de menú en grupos

Los elementos de un menú se pueden agrupar al tener un MenuChild.Separator elemento entre elementos. Visualmente, tendrá un aspecto similar a una línea delgada colocada entre dos elementos.

[VisualStudioContribution]
public static MenuConfiguration MyMenu1 => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        MenuChild.Menu(MyMenu2), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu2`
        MenuChild.Separator,
        MenuChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
        MenuChild.Menu(MyMenu3), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu3`
    },
};

Esto también se puede lograr mediante el MenuChild.Group método para definir un grupo insertado. A continuación, usaría la GroupChild clase para elementos primarios en el grupo.

[VisualStudioContribution]
public static MenuConfiguration MyMenu1 => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Group(
            GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
            GroupChild.Menu(MyMenu2)), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu2`
        MenuChild.Group(
            GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
            GroupChild.Menu(MyMenu3)), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu3`
    },
};

En los dos ejemplos anteriores, el menú resultante sería idéntico en el IDE. El menú MyMenu1 tendría el aspecto del menú en la captura de pantalla siguiente:

Crear una barra de trabajo

Para crear una barra de herramientas con el nuevo modelo de extensibilidad, agregue una propiedad estática ToolbarConfiguration , adornando la clase con el VisualStudioContribution atributo . Esta propiedad estática se puede colocar en cualquier clase del proyecto de extensión. En los nuevos ejemplos del modelo de extensibilidad existen en la Extension clase para simplificar.

[VisualStudioContribution]
public class ExtensionEntrypoint : Extension
{
  [VisualStudioContribution]
  public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%");
}

Dejando la Placement propiedad de como ToolbarConfigurationnull colocará la barra de herramientas en la barra de herramientas estándar y se puede hacer visible seleccionando la barra de herramientas en el View -> Toolbars menú.

ToolbarConfiguration (clase)

La ToolbarConfiguration clase tiene algunas propiedades con las que debe familiarizarse:

Propiedad	Type	Obligatorio	Descripción
DisplayName	Cadena	Sí	Nombre para mostrar predeterminado de la barra de herramientas. Rodea esta cadena con el carácter '%' para habilitar la localización de esta cadena. Consulte la sección Localización de metadatos.
TooltipText	Cadena	No	Texto que se va a mostrar como información sobre herramientas cuando se mantiene el puntero o el foco de la barra de herramientas. Rodea esta cadena con el carácter '%' para habilitar la localización de esta cadena. Consulte la sección Localización de metadatos.
Colocaciones	CommandPlacement[]	No	Especifica los grupos existentes en Visual Studio a los que se asignará la barra de herramientas. Consulte En Colocar un comando en el IDE. Dejar esta propiedad como null colocará la barra de herramientas en la barra de herramientas estándar y se puede hacer visible seleccionando la barra de herramientas en el View -> Toolbars menú.
Children	ToolbarChild[]	No	Describe el conjunto de comandos, menús y grupos que deben estar primarios en esta barra de herramientas. El orden en que se definen estos elementos en la matriz representa el orden en que aparecerán visualmente en el IDE. Consulta en Colocar elementos en una barra de herramientas

Colocar elementos en una barra de herramientas

La colocación de comandos en una barra de herramientas se realiza mediante el ToolbarChild.Command<T> método , reemplazando el argumento template por el nombre de clase de Command.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Command<MyCommand>(),
    },
};

Separación de elementos de la barra de herramientas en grupos

Los elementos de una barra de herramientas se pueden agrupar al tener un ToolbarChild.Separator elemento entre elementos. Visualmente, tendrá un aspecto similar a una línea delgada colocada entre dos elementos.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        ToolbarChild.Separator,
        ToolbarChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

Esto también se puede lograr mediante el ToolbarChild.Group método para definir un grupo insertado. A continuación, usaría la ToolbarChild clase para elementos primarios en el grupo.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Group(
            GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        ToolbarChild.Group(
            GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

En los dos ejemplos aquí, la barra de herramientas resultante sería idéntica en el IDE. La barra de herramientas MyToolbar tendría el aspecto de la barra de herramientas en la captura de pantalla siguiente:

Creación de un grupo

Un grupo es una agrupación visual de elementos en los que se colocará un separador entre los últimos y los primeros elementos de los grupos adyacentes. En las secciones anteriores, describe cómo crear grupos dentro del contexto de la Children propiedad de o MenuConfigurationToolbarConfiguration. También es posible definir grupos dentro de su propio CommandGroupConfiguration. Esto resulta útil cuando desea agrupar un grupo en un menú o barra de herramientas existente en Visual Studio sin definir su propio menú o barra de herramientas. También puede ser útil si desea dar formato al código de una manera que separe las definiciones de grupo de las definiciones de menú y de la barra de herramientas.

Para crear un grupo con el nuevo modelo de extensibilidad, agregue una propiedad estática CommandGroupConfiguration . Esta propiedad estática se puede colocar en cualquier clase del proyecto de extensión. En los nuevos ejemplos del modelo de extensibilidad existen en la Extension clase para simplificar. Si especifica CommandGroupConfiguration un Placement, también debe adornarse con el VisualStudioContribution atributo .

public static CommandGroupConfiguration MyGroup => new();

[VisualStudioContribution]
private static CommandGroupConfiguration MyGroupWithPlacement => new(GroupPlacement.KnownPlacements.ToolsMenu);

Clase CommandGroupConfiguration

La CommandGroupConfiguration clase tiene algunos parámetros con los que debe familiarizarse:

Parámetro	Type	Obligatorio	Descripción
Colocación	GroupPlacement	No	Especifica el menú o la barra de herramientas existentes dentro de Visual Studio a los que se asociará el grupo. Consulte Colocar un grupo en el IDE.
Children	GroupChild[]	No	Describe el conjunto de comandos y menús que deben estar primarios en este grupo. El orden en que se definen estos elementos en la matriz representa el orden en que aparecerán visualmente en el IDE. Ver en Colocar elementos en un grupo

Colocar un grupo en el IDE

Hay un conjunto de lugares bien definidos en Visual Studio donde se pueden colocar comandos. Estas ubicaciones se definen mediante la propiedad CommandPlacement.KnownPlacements de la clase Commands.GroupPlacement. El conjunto actual de KnownPlacements es:

• ToolsMenu - El comando se colocará en un grupo bajo el menú de nivel superior "Herramientas" en Visual Studio.
• ViewOtherWindowsMenu - El comando se colocará en un grupo bajo el menú "Ver" de nivel superior:> "Otras ventanas" en Visual Studio.
• ExtensionsMenu - El comando se colocará en un grupo bajo el menú de nivel superior "Extensiones" en Visual Studio.

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup1 => new(GroupPlacement.KnownPlacements.ToolsMenu);

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup2 => new(GroupPlacement.KnownPlacements.ExtensionsMenu.WithPriority(0x100));

Colocar elementos en un grupo

Los comandos y menús se pueden colocar en grupos mediante la Children propiedad array en .CommandGroupConfiguration

Colocar comandos en un grupo

La colocación de comandos en un grupo se realiza mediante el GroupChild.Command<T> método , reemplazando el argumento de plantilla por el nombre de clase de Command.

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup => new(GroupPlacement.KnownPlacements.ToolsMenu)
{
    Children = new[]
    {
        GroupChild.Command<MyCommand>(),
    },
};

Colocar menús en un grupo

La colocación de menús en un grupo se realiza mediante el GroupChild.Menu método , pasando un MenuConfiguration elemento como parámetro.

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%");

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup => new(GroupPlacement.KnownPlacements.ToolsMenu)
{
    Children = new[]
    {
        GroupChild.Menu(MyMenu),
    },
};

Colocar grupos en un menú o barra de herramientas

La colocación de un grupo en un menú se realiza mediante el MenuChild.Group método , pasando un CommandGroupConfiguration elemento como parámetro. La colocación de un grupo en una barra de herramientas se realiza mediante el ToolbarChild.Group método , pasando un CommandGroupConfiguration elemento como parámetro. Los grupos primarios en menús o barras de herramientas de esta manera no pueden tener la Placement propiedad del CommandGroupConfiguration conjunto en ningún valor excepto null, y no debe adornarse con el VisualStudioContribution atributo .

private static CommandGroupConfiguration MyGroup => new()
{
    Children = new[]
    {
        GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Group(MyGroup),
    },
};

private static CommandGroupConfiguration MyGroup => new()
{
    Children = new[]
    {
        GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
}

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Group(MyGroup),
    },
};

Ordenación de selección de ubicación (prioridad)

Las ubicaciones se ordenan en función del valor de su Priority propiedad cuando están primarios en un control definido en VSCT, en relación con otros elementos primarios en el mismo grupo, menú o barra de herramientas. La propiedad Priority es una unsigned short. El valor predeterminado Priority de y CommandPlacement es 0 y GroupPlacement se puede modificar llamando a los CommandPlacement.WithPriority métodos o GroupPlacement.WithPriority pasando el valor deseadoPriority. Priority También se puede establecer mediante los CommandPlacement.VsctParent métodos y y GroupPlacement.VsctParent pasando directamente el deseadoPriority.

La Priority propiedad no está implicada cuando los elementos primarios a los controles definidos a través de objetos de configuración mediante el modelo de extensibilidad VisualStudio.Extensibility (es decir, el grupo, el menú o la barra de herramientas a los que se va a establecer la barra de herramientas se definió mediante CommandGroupConfiguration, MenuConfigurationo ToolbarConfiguration).

GroupPlacement

GroupPlacement.KnownPlacements.ToolsMenu.WithPriority(0x0500);

// Parenting a group to the "Help" top level menu
GroupPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x0088, priority: 0x0500);

CommandPlacement

CommandPlacement.KnownPlacements.ToolsMenu.WithPriority(0x0500);

// Parenting a command to the "Help -> About" group
CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x016B, priority: 0x0801);