Vue d’ensemble des menus et des barres d’outils

Les menus et les barres d’outils sont la façon dont les utilisateurs accèdent aux commandes dans votre extension. Il s’agit de méthodes graphiques pratiques pour présenter vos commandes aux utilisateurs. En règle générale, les commandes associées sont regroupées dans le même menu ou la même barre d’outils.

Utiliser des menus et des barres d’outils

Cette vue d’ensemble couvre les principaux scénarios d’utilisation des menus et des barres d’outils :

• Créer un menu
• Placer des éléments dans un menu
• Créer une barre d’outils
• Placer des éléments dans une barre d’outils
• Création d’un groupe
• Placer des éléments sur un groupe
• Placer des groupes dans un menu ou une barre d’outils
• Classement de placement (priorité)

Créer un menu

Pour créer un menu avec le nouveau modèle d’extensibilité, ajoutez une propriété statique MenuConfiguration , ornant la classe avec l’attribut VisualStudioContribution . Cette propriété statique peut être placée sur n’importe quelle classe dans votre projet d’extension. Dans les nouveaux exemples de modèle d’extensibilité, ils existent sur la Extension classe par souci de simplicité. Les menus sans enfants visibles ne seront pas visibles dans l’interface utilisateur.

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

Classe MenuConfiguration

La MenuConfiguration classe a quelques paramètres que vous devez connaître :

Paramètre	Type	Requise	Description
Nom d’affichage	Chaîne	Oui	Nom d’affichage par défaut de votre menu. Entourez cette chaîne avec le caractère « % » pour permettre la localisation de cette chaîne. Voir à l’adresse Localiser les métadonnées.
TooltipText	Chaîne	Non	Texte à afficher en tant qu’info-bulle lorsque le menu est pointé ou concentré. Entourez cette chaîne avec le caractère « % » pour permettre la localisation de cette chaîne. Voir à l’adresse Localiser les métadonnées.
Dispositions	CommandPlacement[]	Non	Spécifie les groupes existants dans Visual Studio auxquels le menu sera parenté. Voir à l’adresse Placer un menu dans l’IDE.
Children	MenuChild[]	Non	Décrit l’ensemble de commandes, de menus et de groupes qui doivent être parentés de ce menu. L’ordre dans lequel ces éléments sont définis dans le tableau représente l’ordre dans lequel ils apparaîtront visuellement dans l’IDE. Voir à l’emplacement des éléments dans un menu

Placer un menu dans l’IDE

Les menus sont placés dans l’IDE de la même façon que les commandes. Consultez Placer une commande dans l’IDE.

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

Placer des éléments dans un menu

Le placement sur l’élément d’un menu est effectué en ajoutant des éléments au Children tableau sur le MenuConfiguration. L’ordre dans lequel les éléments sont ajoutés à ce tableau détermine la façon dont ces éléments seront affichés visuellement dans l’IDE.

Placer des commandes dans un menu

Le placement de commandes dans un menu est effectué à l’aide de la MenuChild.Command<T> méthode, en remplaçant l’argument de modèle par le nom de classe du Command.

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

Placer des menus dans un menu

Le placement de menus sur un menu est effectué à l’aide de la MenuChild.Menu méthode, en passant un autre MenuConfiguration en tant que paramètre.

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

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

Séparation des éléments de menu en groupes

Les éléments d’un menu peuvent être regroupés en ayant un MenuChild.Separator élément à l’autre. Visuellement, cela ressemblera à une ligne mince placée entre deux éléments.

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

Cela peut également être effectué à l’aide de la MenuChild.Group méthode pour définir un groupe inline. Vous utiliserez ensuite la GroupChild classe pour les éléments parents dans le groupe.

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

Dans les deux exemples précédents, le menu résultant serait identique dans l’IDE. Le menu ressemblerait au menu MyMenu1 dans la capture d’écran suivante :

Créer une barre d'outils

Pour créer une barre d’outils avec le nouveau modèle d’extensibilité, ajoutez une propriété statique ToolbarConfiguration , ornant la classe avec l’attribut VisualStudioContribution . Cette propriété statique peut être placée sur n’importe quelle classe dans votre projet d’extension. Dans les nouveaux exemples de modèle d’extensibilité, ils existent sur la Extension classe par souci de simplicité.

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

Laissant la Placement propriété de la ToolbarConfiguration barre d’outils telle que null celle-ci placera la barre d’outils standard et peut être rendue visible en sélectionnant la barre d’outils dans le View -> Toolbars menu.

Classe ToolbarConfiguration

La ToolbarConfiguration classe a quelques propriétés que vous devez connaître :

Propriété	Type	Requise	Description
Nom d’affichage	Chaîne	Oui	Nom d’affichage par défaut de votre barre d’outils. Entourez cette chaîne avec le caractère « % » pour permettre la localisation de cette chaîne. Voir à l’adresse Localiser les métadonnées.
TooltipText	Chaîne	Non	Texte à afficher en tant qu’info-bulle lorsque la barre d’outils est pointée ou prioritaire. Entourez cette chaîne avec le caractère « % » pour permettre la localisation de cette chaîne. Voir à l’adresse Localiser les métadonnées.
Dispositions	CommandPlacement[]	Non	Spécifie les groupes existants dans Visual Studio auxquels la barre d’outils sera parentée. Voir à l’adresse Placer une commande dans l’IDE. Laissant cette propriété telle quelle null placera la barre d’outils dans la barre d’outils standard et peut être rendue visible en sélectionnant la barre d’outils dans le View -> Toolbars menu
Children	ToolbarChild[]	Non	Décrit l’ensemble de commandes, de menus et de groupes qui doivent être parentés de cette barre d’outils. L’ordre dans lequel ces éléments sont définis dans le tableau représente l’ordre dans lequel ils apparaîtront visuellement dans l’IDE. Voir à l’emplacement des éléments dans une barre d’outils

Placer des éléments dans une barre d’outils

Le placement de commandes dans une barre d’outils est effectué à l’aide de la ToolbarChild.Command<T> méthode, en remplaçant l’argument de modèle par le nom de classe du Command.

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

Séparation des éléments de barre d’outils en groupes

Les éléments d’une barre d’outils peuvent être regroupés en ayant un ToolbarChild.Separator élément à l’autre. Visuellement, cela ressemblera à une ligne mince placée entre deux éléments.

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

Cela peut également être effectué à l’aide de la ToolbarChild.Group méthode pour définir un groupe inline. Vous utiliserez ensuite la ToolbarChild classe pour les éléments parents dans le groupe.

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

Dans les deux exemples ici, la barre d’outils résultante serait identique dans l’IDE. La barre d’outils MyToolbar ressemble à la barre d’outils dans la capture d’écran ci-dessous :

Créer un groupe

Un groupe est un regroupement visuel d’éléments dans lequel un séparateur sera placé entre les derniers et les premiers éléments des groupes adjacents. Dans les sections ci-dessus, il explique comment créer des groupes à l’intérieur du contexte de la Children propriété d’un MenuConfiguration ou ToolbarConfiguration. Il est également possible de définir des groupes à l’intérieur de leur propre CommandGroupConfiguration. Cela est utile lorsque vous souhaitez parenter un groupe d’un menu ou d’une barre d’outils existant dans Visual Studio sans définir votre propre menu ou barre d’outils. Il peut également être utile si vous souhaitez mettre en forme votre code d’une manière qui sépare vos définitions de groupe de vos définitions de menu et de barre d’outils.

Pour créer un groupe avec le nouveau modèle d’extensibilité, ajoutez une propriété statique CommandGroupConfiguration . Cette propriété statique peut être placée sur n’importe quelle classe dans votre projet d’extension. Dans les nouveaux exemples de modèle d’extensibilité, ils existent sur la Extension classe par souci de simplicité. Si un spécifie un CommandGroupConfigurationPlacement, il doit également être orné de l’attribut VisualStudioContribution .

public static CommandGroupConfiguration MyGroup => new();

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

Classe CommandGroupConfiguration

La CommandGroupConfiguration classe a quelques paramètres que vous devez connaître :

Paramètre	Type	Requise	Description
Placement	GroupPlacement	Non	Spécifie le menu ou la barre d’outils existant dans Visual Studio auquel le groupe sera parenté. Consultez l’article Placer un groupe dans l’IDE.
Children	GroupChild[]	Non	Décrit l’ensemble de commandes et de menus qui doivent être parentés de ce groupe. L’ordre dans lequel ces éléments sont définis dans le tableau représente l’ordre dans lequel ils apparaîtront visuellement dans l’IDE. Voir à l’emplacement des éléments d’un groupe

Placer un groupe dans l’IDE

Il existe un ensemble d’emplacements bien définis dans Visual Studio où les commandes peuvent être placées. Ces placements sont définis par la propriété CommandPlacement.KnownPlacements sur la classe Commands.GroupPlacement. L’ensemble actuel est KnownPlacements :

• ToolsMenu - La commande est placée dans un groupe sous le menu « Outils » de niveau supérieur dans Visual Studio.
• ViewOtherWindowsMenu - La commande est placée dans un groupe sous le menu « Affichage » de niveau supérieur -> « Autres fenêtres » dans Visual Studio.
• ExtensionsMenu - La commande est placée dans un groupe sous le menu « Extensions » de niveau supérieur dans Visual Studio.

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

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

Placer des éléments sur un groupe

Les commandes et les menus peuvent être placés sur des groupes à l’aide de la Children propriété de tableau sur le CommandGroupConfiguration.

Placer des commandes sur un groupe

Le placement de commandes sur un groupe est effectué à l’aide de la GroupChild.Command<T> méthode, en remplaçant l’argument de modèle par le nom de classe du Command.

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

Placer des menus sur un groupe

Le placement de menus sur un groupe est effectué à l’aide de la GroupChild.Menu méthode, en passant un MenuConfiguration paramètre en tant que paramètre.

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

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

Placer des groupes dans un menu ou une barre d’outils

Placer un groupe dans un menu est effectué à l’aide de la MenuChild.Group méthode, en passant un CommandGroupConfiguration paramètre en tant que paramètre. Le placement d’un groupe dans une barre d’outils s’effectue à l’aide de la ToolbarChild.Group méthode, en passant un CommandGroupConfiguration paramètre en tant que paramètre. Les groupes parentés sur les menus ou les barres d’outils de cette façon ne peuvent pas avoir la propriété de l’ensemble PlacementCommandGroupConfiguration sur une valeur sauf null, et il ne doit pas être orné de l’attribut VisualStudioContribution .

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),
    },
};

Classement de placement (priorité)

Les placements sont classés en fonction de la valeur de leur Priority propriété lorsqu’elles sont parentées d’un contrôle défini dans VSCT, par rapport aux autres éléments parentés au même groupe, menu ou barre d’outils. La propriété Priority est un unsigned short. La valeur par défaut d’un et peut être modifiée en appelant ou CommandPlacement.WithPriorityGroupPlacement.WithPriority en passant la valeur souhaitéePriority.0GroupPlacementCommandPlacementPriority Il Priority peut également être défini à l’aide des méthodes et GroupPlacement.VsctParent de la CommandPlacement.VsctParent transmission directe du contenu souhaitéPriority.

La Priority propriété n’est pas impliquée lors du parentage d’éléments à des contrôles définis via des objets de configuration à l’aide du modèle VisualStudio.Extensibility (c’est-à-dire le groupe, le menu ou la barre d’outils parentée à l’aide CommandGroupConfigurationde , 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);