Visão geral de menus e barras de ferramentas

Menus e barras de ferramentas são a maneira como os usuários acessam comandos em sua extensão. São formas gráficas convenientes de apresentar seus comandos aos usuários. Normalmente, os comandos relacionados são agrupados no mesmo menu ou barra de ferramentas.

Trabalhar com menus e barras de ferramentas

Esta visão geral aborda estes principais cenários para trabalhar com menus e barras de ferramentas:

• Criar um menu
• Colocar itens em um menu
• Criar uma barra de ferramentas
• Colocar itens em uma barra de ferramentas
• Criar um grupo
• Colocar itens em um grupo
• Colocar grupos em um menu ou barra de ferramentas
• Ordenação de posicionamento (Prioridade)

Criar um menu

Para criar um menu com o novo Modelo de Extensibilidade, adicione uma propriedade estática MenuConfiguration , adornando a classe com o VisualStudioContribution atributo. Essa propriedade estática pode ser colocada em qualquer classe em seu projeto de extensão. Nos novos exemplos de Modelo de Extensibilidade, eles existem na Extension classe para simplificar. Menus sem filhos visíveis não estarão visíveis na interface do usuário.

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

MenuConfiguration classe

A MenuConfiguration classe tem alguns parâmetros com os quais você deve se familiarizar:

Parâmetro	Type	Obrigatória	Descrição
DisplayName	String	Sim	O nome de exibição padrão do menu. Envolva essa cadeia de caracteres com o caractere '%' para habilitar a localização dessa cadeia de caracteres. Consulte em Localizar metadados.
TooltipText	String	Não	O texto a ser exibido como a dica de ferramenta quando o menu estiver focalizado ou focalizado. Envolva essa cadeia de caracteres com o caractere '%' para habilitar a localização dessa cadeia de caracteres. Consulte em Localizar metadados.
Posicionamentos	CommandPlacement[]	Não	Especifica os grupos existentes no Visual Studio que o menu será parented para. Consulte em Colocar um menu no IDE.
Filhos	MenuChild[]	Não	Descreve o conjunto de comandos, menus e grupos que devem ser parentados para este menu. A ordem em que esses itens são definidos na matriz representa a ordem em que eles aparecerão visualmente no IDE. Veja em Colocar itens em um menu

Colocar um menu no IDE

Os menus são colocados no IDE da mesma forma que os comandos. Consulte Colocar um comando no IDE.

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

Colocar itens em um menu

A colocação no item em um menu é feita adicionando itens à Children matriz no MenuConfiguration. A ordem em que os itens são adicionados a essa matriz determina como esses itens serão exibidos visualmente no IDE.

Colocando comandos em um menu

A colocação de comandos em um menu é feita usando o método, substituindo o MenuChild.Command<T> argumento do modelo pelo nome da classe do Command.

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

Colocando menus em um menu

A colocação de menus em um menu é feita usando o MenuChild.Menu método, passando outro 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),
    },
};

Separando itens de menu em grupos

Os itens dentro de um menu podem ser agrupados tendo um MenuChild.Separator entre os itens. Visualmente, isso se parecerá com uma linha fina colocada entre dois itens.

[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`
    },
};

Isso também pode ser feito usando o MenuChild.Group método para definir um grupo embutido. Em seguida, você usaria a GroupChild classe para criar itens pai para o 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`
    },
};

Nos dois exemplos anteriores, o menu resultante seria idêntico no IDE. O menu seria parecido com o menu MyMenu1 na captura de tela a seguir:

Criar uma barra de ferramentas

Para criar uma barra de ferramentas com o novo Modelo de Extensibilidade, adicione uma propriedade estática ToolbarConfiguration , adornando a classe com o VisualStudioContribution atributo. Essa propriedade estática pode ser colocada em qualquer classe em seu projeto de extensão. Nos novos exemplos de Modelo de Extensibilidade, Extension eles existem na classe para simplificar.

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

Deixar a propriedade do as null colocará a barra de ferramentas na barra de ferramentas padrão e poderá ficar visível selecionando a Placement barra de ToolbarConfiguration ferramentas no View -> Toolbars menu.

ToolbarConfiguration classe

A ToolbarConfiguration classe tem algumas propriedades com as quais você deve se familiarizar:

Propriedade	Type	Obrigatória	Descrição
DisplayName	String	Sim	O nome de exibição padrão da barra de ferramentas. Envolva essa cadeia de caracteres com o caractere '%' para habilitar a localização dessa cadeia de caracteres. Consulte em Localizar metadados.
TooltipText	String	Não	O texto a ser exibido como a dica de ferramenta quando a barra de ferramentas estiver focalizada ou focalizada. Envolva essa cadeia de caracteres com o caractere '%' para habilitar a localização dessa cadeia de caracteres. Consulte em Localizar metadados.
Posicionamentos	CommandPlacement[]	Não	Especifica os grupos existentes no Visual Studio que a barra de ferramentas será parented para. Consulte em Colocar um comando no IDE. Deixando essa propriedade como null colocará a barra de ferramentas na barra de ferramentas padrão e pode ser tornado visível selecionando a barra de ferramentas no View -> Toolbars menu
Filhos	ToolbarChild[]	Não	Descreve o conjunto de comandos, menus e grupos que devem ser parentados para esta barra de ferramentas. A ordem em que esses itens são definidos na matriz representa a ordem em que eles aparecerão visualmente no IDE. Consulte em Colocar itens em uma barra de ferramentas

Colocar itens em uma barra de ferramentas

A colocação de comandos em uma barra de ferramentas é feita usando o método, substituindo o ToolbarChild.Command<T> argumento do modelo pelo nome da classe do Command.

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

Separando itens da barra de ferramentas em grupos

Os itens dentro de uma barra de ferramentas podem ser agrupados por meio de um ToolbarChild.Separator entre itens. Visualmente, isso se parecerá com uma linha fina colocada entre dois itens.

[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`
    },
};

Isso também pode ser feito usando o ToolbarChild.Group método para definir um grupo embutido. Em seguida, você usaria a ToolbarChild classe para criar itens pai para o 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`
    },
};

Nos dois exemplos aqui, a barra de ferramentas resultante seria idêntica no IDE. A barra de ferramentas seria semelhante à barra de ferramentas na captura de MyToolbar tela abaixo:

Criar um grupo

Um grupo é um agrupamento visual de itens onde um separador será colocado entre o último e o primeiro itens de grupos adjacentes. Nas seções acima, ele descreve como criar grupos dentro do contexto da Children propriedade de um MenuConfiguration ou ToolbarConfiguration. Também é possível definir grupos dentro de seus próprios CommandGroupConfigurationgrupos. Isso é útil quando você gostaria de pai de um grupo para um menu existente ou barra de ferramentas no Visual Studio sem definir seu próprio menu ou barra de ferramentas. Também pode ser útil se você quiser formatar seu código de uma maneira que separe suas definições de grupo de suas definições de menu e barra de ferramentas.

Para criar um grupo com o novo Modelo de Extensibilidade, adicione uma propriedade estática CommandGroupConfiguration . Essa propriedade estática pode ser colocada em qualquer classe em seu projeto de extensão. Nos novos exemplos de Modelo de Extensibilidade, Extension eles existem na classe para simplificar. Se um especifica um CommandGroupConfigurationPlacement, ele também deve ser adornado com o VisualStudioContribution atributo.

public static CommandGroupConfiguration MyGroup => new();

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

CommandGroupConfiguration classe

A CommandGroupConfiguration classe tem alguns parâmetros com os quais você deve se familiarizar:

Parâmetro	Type	Obrigatória	Descrição
Colocação	GroupPlacement	Não	Especifica o menu ou barra de ferramentas existente no Visual Studio para o qual o grupo será parentado. Consulte em Colocar um grupo no IDE.
Filhos	GrupoCriança[]	Não	Descreve o conjunto de comandos e menus que devem ser parentados para este grupo. A ordem em que esses itens são definidos na matriz representa a ordem em que eles aparecerão visualmente no IDE. Veja em Colocar itens em um grupo

Colocar um grupo no IDE

Há um conjunto de locais bem definidos no Visual Studio onde os comandos podem ser colocados. Esses posicionamentos são definidos pela propriedade CommandPlacement.KnownPlacements na classe Commands.GroupPlacement. O conjunto atual de KnownPlacements é:

• ToolsMenu - O comando será colocado em um grupo sob o menu de nível superior "Ferramentas" no Visual Studio.
• ViewOtherWindowsMenu - O comando será colocado em um grupo sob o nível superior "View" -> "Other Windows" menu no Visual Studio.
• ExtensionsMenu - O comando será colocado em um grupo sob o menu de nível superior "Extensões" no Visual Studio.

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

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

Colocar itens em um grupo

Comandos e menus podem ser colocados em grupos usando a Children propriedade array no CommandGroupConfiguration.

Colocar comandos em um grupo

A colocação de comandos em um grupo é feita usando o método, substituindo o GroupChild.Command<T> argumento do modelo pelo nome da classe do Command.

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

Colocar menus em um grupo

A colocação de menus em um grupo é feita usando o GroupChild.Menu método, passando um MenuConfiguration 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 em um menu ou barra de ferramentas

A colocação de um grupo em um menu é feita usando o MenuChild.Group método, passando um CommandGroupConfiguration como parâmetro. A colocação de um grupo em uma barra de ferramentas é feita usando o ToolbarChild.Group método, passando um CommandGroupConfiguration como parâmetro. Grupos criados para menus ou barras de ferramentas dessa maneira não podem ter a PlacementCommandGroupConfiguration propriedade do conjunto como qualquer valor, exceto null, e não devem ser adornados com o 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),
    },
};

Ordenação de posicionamento (Prioridade)

Os posicionamentos são ordenados com base no valor de sua Priority propriedade quando parentais de um controle definido no VSCT, em relação a outros itens parentados do mesmo grupo, menu ou barra de ferramentas. A propriedade Priority é um unsigned short. O valor padrão Priority para a CommandPlacement e é 0 e GroupPlacement pode ser modificado chamando os CommandPlacement.WithPriority métodos ouGroupPlacement.WithPriority, passando o valor desejadoPriority. O Priority também pode ser definido usando os CommandPlacement.VsctParent métodos e e GroupPlacement.VsctParent passando o desejado Priority diretamente.

A Priority propriedade não está envolvida ao criar itens pai para controles definidos por meio de objetos de configuração usando o modelo VisualStudio.Extensibility (ou seja, o grupo, menu ou barra de ferramentas para o qual o parente foi definido usando CommandGroupConfiguration, MenuConfigurationou 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);