メニューとツール バーの概要

メニューとツール バーは、ユーザーが拡張機能のコマンドにアクセスする方法です。 これらは、ユーザーにコマンドを表示するための便利なグラフィカルな方法です。 通常、関連するコマンドは、同じメニューやツール バーにまとめられます。

メニューとツール バーを操作する

この概要では、メニューとツール バーを操作するための次の一般的なシナリオについて説明します。

• メニューを作成する
• メニューに項目を配置する
• ツール バーを作成する
• ツール バーに項目を配置する
• グループを作成する
• グループにアイテムを配置する
• メニューまたはツール バーにグループを配置する
• 配置の順序 (優先順位)

メニューを作成します

新しい機能拡張モデルを使用してメニューを作成するには、静的 MenuConfiguration プロパティを追加し、クラスに属性を VisualStudioContribution 付けます。 この静的プロパティは、拡張機能プロジェクト内の任意のクラスに配置できます。 新しい機能拡張モデルのサンプルでは、わかりやすくするためにクラスに Extension 存在します。 子が表示されていないメニューは UI に表示されません。

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

MenuConfiguration クラス

この MenuConfiguration クラスには、理解しておく必要があるいくつかのパラメーターがあります。

パラメーター	タイプ	Required	説明
表示名	String	はい	メニューの既定の表示名。 この文字列を '%' 文字で囲み、この文字列をローカライズできるようにします。 「メタデータのローカライズ」を参照してください。
Tooltiptext	String	いいえ	メニューがホバーまたはフォーカスされたときにヒントとして表示するテキスト。 この文字列を '%' 文字で囲み、この文字列をローカライズできるようにします。 「メタデータのローカライズ」を参照してください。
配置	CommandPlacement[]	いいえ	メニューの親となる Visual Studio 内の既存のグループを指定します。 IDE にメニューを配置するを参照してください。
Children	MenuChild[]	いいえ	このメニューの親にする必要があるコマンド、メニュー、グループのセットについて説明します。 これらの項目が配列内で定義される順序は、IDE で視覚的に表示される順序を表します。 「メニューに 項目を配置する」を参照

IDE にメニューを配置する

メニューは、コマンドと同じように IDE に配置されます。 IDE にコマンドを配置するを参照してください。

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

メニューに項目を配置する

メニューに項目を配置するには、上の配列MenuConfigurationに項目をChildren追加します。 この配列に項目を追加する順序によって、IDE でこれらの項目を視覚的に表示する方法が決まります。

メニューにコマンドを配置する

メニューにコマンドを配置するには、メソッドを MenuChild.Command<T> 使用して、テンプレート引数をクラス名 Commandに置き換えます。

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

メニューにメニューを配置する

メニューにメニューを配置するには、メソッドを MenuChild.Menu 使用して、別 MenuConfiguration のメニューをパラメーターとして渡します。

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

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

メニュー項目をグループに分割する

メニュー内の項目は、項目間を持つこと MenuChild.Separator によってグループ化できます。 視覚的には、これは 2 つの項目の間に配置された細い線のように見えます。

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

これは、インラインでグループを定義するメソッドを MenuChild.Group 使用して行うこともできます。 その後、このクラスを GroupChild 使用して、グループに対する項目を親にします。

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

前の 2 つの例では、結果のメニューは IDE で同じになります。 メニュー MyMenu1 は、次のスクリーンショットのメニューのようになります。

ツールバーの作成

新しい機能拡張モデルを使用してツール バーを作成するには、静的 ToolbarConfiguration プロパティを追加し、クラスに属性を VisualStudioContribution 付けます。 この静的プロパティは、拡張機能プロジェクト内の任意のクラスに配置できます。 新しい機能拡張モデルのサンプルでは、わかりやすくするためにクラスに Extension 存在します。

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

as の PlacementToolbarConfigurationnull プロパティをそのままにすると、ツールバーは標準ツールバー バーに配置され、メニューの View -> Toolbars ツールバーを選択して表示できます。

ToolbarConfiguration クラス

この ToolbarConfiguration クラスには、使い慣れたいくつかのプロパティがあります。

プロパティ	タイプ	Required	説明
表示名	String	はい	ツール バーの既定の表示名。 この文字列を '%' 文字で囲み、この文字列をローカライズできるようにします。 「メタデータのローカライズ」を参照してください。
Tooltiptext	String	いいえ	ツール バーがポイントまたはフォーカスされたときにヒントとして表示するテキスト。 この文字列を '%' 文字で囲み、この文字列をローカライズできるようにします。 「メタデータのローカライズ」を参照してください。
配置	CommandPlacement[]	いいえ	ツール バーの親となる Visual Studio 内の既存のグループを指定します。 「IDE にコマンドを配置する」を参照してください。 このプロパティ null はそのままにすると、ツールバーは標準ツールバー バーに配置され、メニューの View -> Toolbars ツールバーを選択して表示できます。
Children	ToolbarChild[]	いいえ	このツール バーの親にする必要があるコマンド、メニュー、グループのセットについて説明します。 これらの項目が配列内で定義される順序は、IDE で視覚的に表示される順序を表します。 「ツールバーに項目を配置する」を参照

ツール バーに項目を配置する

ツール バーにコマンドを配置するには、このメソッドを ToolbarChild.Command<T> 使用して、テンプレート引数をクラス名 Commandに置き換えます。

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

ツール バー項目をグループに分割する

ツールバー内の項目は、項目間を持つこと ToolbarChild.Separator によってグループ化できます。 視覚的には、これは 2 つの項目の間に配置された細い線のように見えます。

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

これは、インラインでグループを定義するメソッドを ToolbarChild.Group 使用して行うこともできます。 その後、このクラスを ToolbarChild 使用して、グループに対する項目を親にします。

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

ここでの 2 つの例では、結果として得られるツール バーは IDE で同じになります。 ツール バー MyToolbar は、次のスクリーンショットのツール バーのようになります。

グループの作成

グループは、隣接するグループの最後の項目と最初の項目の間に区切り記号が配置される項目の視覚的なグループです。 上記のセクションでは、a または ToolbarConfiguration. のプロパティMenuConfigurationのコンテキスト内にグループを作成するChildren方法について説明します。 独自のグループ内 CommandGroupConfigurationでグループを定義することもできます。 これは、独自のメニューまたはツール バーを定義せずに、Visual Studio の既存のメニューまたはツール バーにグループを親にする場合に便利です。 また、グループ定義をメニューやツール バーの定義から分離する方法でコードを書式設定する場合にも便利です。

新しい機能拡張モデルを使用してグループを作成するには、静的 CommandGroupConfiguration プロパティを追加します。 この静的プロパティは、拡張機能プロジェクト内の任意のクラスに配置できます。 新しい機能拡張モデルのサンプルでは、わかりやすくするためにクラスに Extension 存在します。 a が CommandGroupConfiguration a を指定する Placement場合は、属性で修飾 VisualStudioContribution する必要もあります。

public static CommandGroupConfiguration MyGroup => new();

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

CommandGroupConfiguration クラス

この CommandGroupConfiguration クラスには、理解しておく必要があるいくつかのパラメーターがあります。

パラメーター	タイプ	Required	説明
配置	GroupPlacement	いいえ	グループの親となる Visual Studio 内の既存のメニューまたはツール バーを指定します。 「IDE にグループを配置する」を参照してください。
Children	GroupChild[]	いいえ	このグループの親にする必要があるコマンドとメニューのセットについて説明します。 これらの項目が配列内で定義される順序は、IDE で視覚的に表示される順序を表します。 「グループにアイテムを配置する」を参照

IDE にグループを配置する

Visual Studio には、コマンドを配置できる明確に定義された場所のセットがあります。 これらの配置は、クラスCommands.GroupPlacementのプロパティCommandPlacement.KnownPlacementsによって定義されます。 現在の KnownPlacements セットは次のとおりです。

• ToolsMenu - コマンドは、Visual Studio の最上位レベルの [ツール] メニューの下のグループに配置されます。
• ViewOtherWindowsMenu - コマンドは、Visual Studio の最上位レベルの [表示] -> [その他のウィンドウ] メニューの下のグループに配置されます。
• ExtensionsMenu - コマンドは、Visual Studio の最上位レベルの [拡張機能] メニューの下のグループに配置されます。

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

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

グループにアイテムを配置する

の配列プロパティを使用して、コマンドとメニューを Children グループに CommandGroupConfiguration配置できます。

グループにコマンドを配置する

グループにコマンドを配置するには、メソッドを GroupChild.Command<T> 使用して、テンプレート引数をクラス名 Commandに置き換えます。

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

グループにメニューを配置する

グループにメニューを配置するには、メソッドを GroupChild.Menu 使用して、パラメーターとして a を MenuConfiguration 渡します。

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

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

メニューまたはツール バーにグループを配置する

メニューにグループを配置するには、メソッドを MenuChild.Group 使用して、パラメーターとして a を CommandGroupConfiguration 渡します。 ツール バーにグループを配置するには、メソッドを ToolbarChild.Group 使用して、パラメーターとして a を CommandGroupConfiguration 渡します。 この方法でメニューまたはツールバーに親されているグループは、セットのプロパティをPlacement他nullのCommandGroupConfiguration値にすることはできません。また、属性で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),
    },
};

配置の順序 (優先順位)

配置は、VSCT で定義されているコントロールに対して、同じグループ、メニュー、またはツール バーに親されている他の Priority 項目を基準にして、そのプロパティの値に基づいて並べ替えます。 Priority プロパティは unsigned short です。 a と GroupPlacement is のCommandPlacement既定値Priority。0またはメソッドを呼び出CommandPlacement.WithPriorityGroupPlacement.WithPriorityして、目的Priorityの値を渡すことによって変更できます。 またPriority、and GroupPlacement.VsctParent メソッドを使用してCommandPlacement.VsctParent、必要Priorityなメソッドを直接渡すことによっても設定できます。

このプロパティはPriority、VisualStudio.Extensibility モデルを使用して構成オブジェクトを使用して定義されたコントロールに項目を親にするとき (つまり、親にされているグループ、メニュー、またはツール バーが 、MenuConfigurationまたはToolbarConfigurationを使用してCommandGroupConfiguration定義されている場合) には関係しません。

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