VSPackage でユーザーインターフェイス要素を追加する方法

VSPackage では、 .vsct ファイルを使用して、メニュー、ツールバー、ツールウィンドウなどのユーザーインターフェイス (UI) 要素を Visual Studio に追加できます。

UI 要素の設計ガイドラインについては、 Visual Studio のユーザーエクスペリエンスガイドラインを参照してください。

Visual Studio コマンドテーブルのアーキテクチャ

前述のように、コマンドテーブルアーキテクチャでは、前述のアーキテクチャの原則がサポートされています。コマンドテーブルアーキテクチャの抽象化、データ構造、およびツールの背後にあるテネトは次のとおりです。

基本的な項目には、メニュー、コマンド、グループの 3 種類があります。メニューは、メニュー、サブメニュー、ツールバー、またはツールウィンドウとして UI で公開できます。コマンドは、ユーザーが IDE で実行できるプロシージャであり、メニュー項目、ボタン、リストボックス、またはその他のコントロールとして公開できます。グループは、メニューとコマンドの両方のコンテナーです。
各項目は、項目、他の項目に対する相対的な優先順位、およびその動作を変更するフラグを記述する定義によって指定されます。
各項目には、アイテムの親を記述する配置があります。項目には複数の親を含めることができるため、UI 内の複数の場所に表示できます。

すべてのコマンドは、その親としてグループを持つ必要があります。そのグループ内の唯一の子である場合でもそうです。すべての標準メニューにも親グループが必要です。ツールバーとツールウィンドウは、独自の親として機能します。グループは、親として Visual Studio のメインメニューバー、または任意のメニュー、ツールバー、またはツールウィンドウを持つことができます。

項目の定義方法

.vsct ファイルは XML 形式です。パッケージの UI 要素を定義し、それらの要素が IDE のどこに表示されるかを決定します。パッケージ内のすべてのメニュー、グループ、またはコマンドには、最初に Symbols セクションに GUID と ID が割り当てられます。 .vsct ファイルの残りの部分では、各メニュー、コマンド、およびグループは、GUID と ID の組み合わせによって識別されます。次の例は、Symbolsを選択したときに Visual Studio パッケージテンプレートによって生成される一般的なセクションを示しています。

<Symbols>
  <!-- This is the package guid. -->
  <GuidSymbol name="guidMenuTextPkg" value="{b1253bc6-d266-402b-89e7-5e3d3b22c746}" />

  <!-- This is the guid used to group the menu commands together -->
  <GuidSymbol name="guidMenuTextCmdSet" value="{a633d4e4-6c65-4436-a138-1abeba7c9a69}">
    <IDSymbol name="MyMenuGroup" value="0x1020" />
    <IDSymbol name="cmdidMyCommand" value="0x0100" />
  </GuidSymbol>

  <GuidSymbol name="guidImages" value="{53323d9a-972d-4671-bb5b-9e418480922f}">
    <IDSymbol name="bmpPic1" value="1" />
    <IDSymbol name="bmpPic2" value="2" />
    <IDSymbol name="bmpPicSearch" value="3" />
    <IDSymbol name="bmpPicX" value="4" />
    <IDSymbol name="bmpPicArrows" value="5" />
  </GuidSymbol>
</Symbols>

Symbols セクションの最上位要素は GuidSymbol 要素です。 GuidSymbol 要素は、パッケージとそのコンポーネントパーツを識別するために IDE によって使用される GUID に名前をマップします。

注

GUID は、Visual Studio パッケージテンプレートによって自動的に生成されます。 [ツール] メニューの [GUID の作成] をクリックして、一意の GUID を作成することもできます。

最初の GuidSymbol 要素 ( guid<PackageName>Pkg) は、パッケージ自体の GUID です。これは、パッケージの読み込みに Visual Studio によって使用される GUID です。通常、子要素はありません。

慣例により、メニューとコマンドは 2 番目の GuidSymbol 要素、 guid<PackageName>CmdSet、ビットマップの下にグループ化され、ビットマップは 3 番目の GuidSymbol 要素 ( guidImages) の下にあります。この規則に従う必要はありませんが、各メニュー、グループ、コマンド、およびビットマップは、 GuidSymbol 要素の子である必要があります。

パッケージコマンドセットを表す 2 番目の GuidSymbol 要素には、いくつかの IDSymbol 要素があります。各 IDSymbol 要素は、名前を数値にマップし、コマンドセットの一部であるメニュー、グループ、またはコマンドを表します。 3 番目のIDSymbol要素のGuidSymbol要素は、コマンドのアイコンとして使用できるビットマップを表します。 GUID と ID のペアはアプリケーションで一意である必要があるため、同じ GuidSymbol 要素の 2 つの子が同じ値を持つことはありません。

メニュー、グループ、およびコマンド

メニュー、グループ、またはコマンドに GUID と ID がある場合は、IDE に追加できます。すべての UI 要素には、次のものが必要です。

GuidSymbol属性は、UI要素が定義されているguid要素の名前と一致します。
関連付けられているid要素の名前と一致するIDSymbol属性。

guid属性とid属性が一緒に、UI 要素のシグネチャを構成します。

親メニューまたはグループ内の UI 要素の配置を決定する priority 属性。
親メニューまたはグループの署名を指定する属性とguid属性を持つ id。

メニュー

各メニューは、セクションの Menusとして定義されます。メニューには、 guid、 id、および priority 属性、および Parent 要素、および次の追加の属性と子が必要です。

メニューをメニューの一種として IDE に表示するか、ツールバーとして表示するかを指定する type 属性。
IDE のメニューのタイトルを指定する ButtonText 要素と、メニューにアクセスするためにコマンドウィンドウで使用される名前を指定する CommandName 要素を含む Strings 要素。
省略可能なフラグ。 CommandFlag 要素は、IDE での外観や動作を変更するためにメニュー定義に表示される場合があります。

ツールバーなどのドッキング可能な要素でない限り、すべての Menu 要素は親としてグループを持つ必要があります。ドッキング可能なメニューは自分自身が親になっています。 type属性のメニューと値の詳細については、Menu 要素のドキュメントを参照してください。

次の例は、Visual Studio メニューバーの [ ツール ] メニューの横に表示されるメニューを示しています。

<Menu guid="guidTopLevelMenuCmdSet" id="TopLevelMenu" priority="0x700" type="Menu">
  <Parent guid="guidSHLMainMenu" id="IDG_VS_MM_TOOLSADDINS" />
  <Strings>
    <ButtonText>TestMenu</ButtonText>
    <CommandName>TestMenu</CommandName>
  </Strings>
</Menu>

Groups

グループは、Groups ファイルのセクションで定義されている項目です。グループは単なるコンテナーです。 IDE では、それらはメニューの区切り線としてのみ表示されます。したがって、 Group 要素は、そのシグネチャ、優先度、および親によってのみ定義されます。

グループは、メニュー、別のグループ、またはそれ自体を親として持つことができます。ただし、親は通常、メニューまたはツールバーです。前の例のメニューは、 IDG_VS_MM_TOOLSADDINS グループの子であり、そのグループは Visual Studio メニューバーの子です。次の例のグループは、前の例のメニューの子です。

<Group guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" priority="0x0600">
  <Parent guid="guidTopLevelMenuCmdSet" id="TopLevelMenu"/>
</Group>

これはメニューの一部であるため、通常、このグループにはコマンドが含まれます。ただし、他のメニューを含めることもできます。次の例に示すように、サブメニューの定義方法は次のとおりです。

<Menu guid="guidTopLevelMenuCmdSet" id="SubMenu" priority="0x0100" type="Menu">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup"/>
  <Strings>
    <ButtonText>Sub Menu</ButtonText>
    <CommandName>Sub Menu</CommandName>
  </Strings>
</Menu>

Commands

IDE に提供されるコマンドは、 Button 要素または Combo 要素として定義されます。メニューまたはツールバーに表示するには、コマンドの親としてグループが必要です。

Buttons

ボタンは、 Buttons セクションで定義します。ユーザーが 1 つのコマンドを実行するためにクリックしたメニュー項目、ボタン、またはその他の要素は、ボタンと見なされます。一部のボタンの種類には、リスト機能を含めることもできます。ボタンには、メニューと同じ必須属性と省略可能な属性があり、IDE 内のボタンを表すビットマップの GUID と ID を指定する Icon 要素を持つこともできます。ボタンとその属性の詳細については、 Buttons 要素のドキュメントを参照してください。

次の例のボタンは、前の例のグループの子であり、そのグループの親メニューのメニュー項目として IDE に表示されます。

<Button guid="guidTopLevelMenuCmdSet" id="cmdidTestCommand" priority="0x0100" type="Button">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" />
  <Icon guid="guidImages" id="bmpPic1" />
  <Strings>
    <CommandName>cmdidTestCommand</CommandName>
    <ButtonText>Test Command</ButtonText>
  </Strings>
</Button>

コンボ

コンボは、 Combos セクションで定義されます。各 Combo 要素は、IDE のドロップダウンリストボックスを表します。リストボックスは、コンボの type 属性の値に応じて、ユーザーが書き込み可能な場合とできない場合があります。コンボには、ボタンと同じ要素と動作があり、次の追加属性を持つこともできます。

ピクセル幅を指定する defaultWidth 属性。
リストボックスに表示される項目を含むリストを指定する idCommandList 属性。コマンドリストは、コンボを含む同じ GuidSymbol ノードで宣言する必要があります。

次の例では、コンボ要素を定義します。

<Combos>
  <Combo guid="guidFirstToolWinCmdSet"
         id="cmdidWindowsMediaFilename"
         priority="0x0100" type="DynamicCombo"
         idCommandList="cmdidWindowsMediaFilenameGetList"
         defaultWidth="130">
    <Parent guid="guidFirstToolWinCmdSet"
            id="ToolbarGroupID" />
    <CommandFlag>IconAndText</CommandFlag>
    <CommandFlag>CommandWellOnly</CommandFlag>
    <CommandFlag>StretchHorizontally</CommandFlag>
    <Strings>
      <CommandName>Filename</CommandName>
      <ButtonText>Enter a Filename</ButtonText>
    </Strings>
  </Combo>
</Combos>

ビットマップ

アイコンと共に表示されるコマンドには、GUID と ID を使用してビットマップを参照する Icon 要素が含まれている必要があります。各ビットマップは、セクションの Bitmapsとして定義されます。 Bitmap定義に必要な属性は、ソースファイルを指すguidとhrefだけです。ソースファイルがリソースストリップの場合は、ストリップで使用可能なイメージを一覧表示するために 、usedList 属性も必要です。詳細については、 Bitmap 要素のドキュメントを参照してください。

子育て

次のルールは、アイテムが別のアイテムを親として呼び出す方法を制御します。

要素	コマンドテーブルのこのセクションで定義されている	(親として、または `CommandPlacements` セクション内の配置によって、またはその両方として) 含まれる場合があります。	(親と呼ばれる) を含む場合があります
グループ	Groups 要素、IDE、その他の VSPackage	メニュー、グループ、項目自体	メニュー、グループ、およびコマンド
メニュー	Menus 要素、IDE、その他の VSPackage	1 ~ n 個のグループ	0 ~ n 個のグループ
ツールバー	Menus 要素、IDE、その他の VSPackage	アイテム自体	0 ~ n 個のグループ
メニュー項目	Buttons 要素、IDE、その他の VSPackage	1 ~ n 個のグループ、項目自体	-0 から n 個のグループ
Button	Buttons 要素、IDE、その他の VSPackage	1 ~ n 個のグループ、項目自体
複合	Combos 要素、IDE、その他の VSPackage	1 ~ n 個のグループ、項目自体

メニュー、グループ、またはコマンドは、IDE 内の複数の場所に表示できます。項目を複数の場所に表示するには、CommandPlacementsとしてセクションに追加する必要があります。任意のメニュー、グループ、またはコマンドをコマンド配置として追加できます。ただし、ツールバーは状況依存の複数の場所に表示できないため、この方法では配置できません。

コマンド配置には、 guid、 id、および priority 属性があります。 GUID と ID は、配置されている項目のものと一致する必要があります。 priority属性は、他の項目に関する項目の配置を制御します。 IDE が同じ優先度を持つ 2 つ以上の項目をマージすると、パッケージがビルドされるたびにパッケージリソースが同じ順序で読み取られるという保証がないため、配置は未定義になります。

メニューまたはグループが複数の場所に表示される場合、そのメニューまたはグループのすべての子が各インスタンスに表示されます。

コマンドの可視性とコンテキスト

複数の VSPackage がインストールされている場合、メニュー、メニュー項目、ツールバーが豊富に用意されていると、IDE が煩雑になる可能性があります。この問題を回避するには、可視性制約とコマンドフラグを使用して、個々の UI 要素 の可視性 を制御できます。

可視性の制約

表示制約は、セクションの VisibilityConstraintsとして設定されます。可視性制約は、ターゲット項目が表示される特定の UI コンテキストを定義します。このセクションに含まれるメニューまたはコマンドは、定義されたコンテキストのいずれかがアクティブな場合にのみ表示されます。このセクションでメニューまたはコマンドが参照されていない場合は、常に既定で表示されます。このセクションはグループには適用されません。

VisibilityItem 要素には、ターゲット UI 要素の guid と id 、および contextの 3 つの属性が必要です。 context属性は、ターゲット項目が表示されるタイミングを指定し、有効な UI コンテキストを値として受け取ります。 Visual Studio の UI コンテキスト定数は、 VSConstants クラスのメンバーです。すべての VisibilityItem 要素は、1 つのコンテキスト値のみを受け取ることができます。 2 番目のコンテキストを適用するには、次の例に示すように、同じ項目を指す 2 つ目の VisibilityItem 要素を作成します。

<VisibilityConstraints>
  <VisibilityItem guid="guidSolutionToolbarCmdSet"
        id="cmdidTestCmd"
        context="UICONTEXT_SolutionHasSingleProject" />
  <VisibilityItem guid="guidSolutionToolbarCmdSet"
        id="cmdidTestCmd"
        context="UICONTEXT_SolutionHasMultipleProjects" />
</VisibilityConstraints>

コマンドフラグ

次のコマンドフラグは、適用されるメニューとコマンドの表示に影響を与える可能性があります。

AlwaysCreate グループやボタンがない場合でもメニューが作成されます。

有効範囲: Menu

CommandWellOnly コマンドが最上位メニューに表示されず、追加のシェルカスタマイズ (キーへのバインドなど) に使用できるようにする場合は、このフラグを適用します。 VSPackage がインストールされたら、[ オプション] ダイアログボックスを開き、[ キーボード環境 ] カテゴリでコマンドの配置を編集することで、これらのコマンドをカスタマイズできます。ショートカットメニュー、ツールバー、メニューコントローラー、サブメニューの配置には影響しません。

有効: Button、 Combo

DefaultDisabled 既定では、コマンドを実装する VSPackage が読み込まれていないか、QueryStatus メソッドが呼び出されていない場合、コマンドは無効になります。

有効: Button、 Combo

DefaultInvisible 既定では、コマンドを実装する VSPackage が読み込まれていないか、QueryStatus メソッドが呼び出されていない場合、コマンドは表示されません。

DynamicVisibility フラグと組み合わせる必要があります。

有効: Button、 Combo、 Menu

DynamicVisibility コマンドの可視性は、 QueryStatus メソッドまたは VisibilityConstraints セクションに含まれるコンテキスト GUID を使用して変更できます。

ツールバーではなくメニューに表示されるコマンドに適用されます。 OLECMDF_INVISIBLE メソッドからQueryStatus フラグが返された場合、最上位のツールバー項目は無効にできますが、非表示にすることはできません。

メニューでは、このフラグは、メンバーが非表示になったときに自動的に非表示にする必要があることを示します。このフラグは通常、サブメニューに割り当てられます。最上位のメニューには既にこの動作があるためです。

DefaultInvisible フラグと組み合わせる必要があります。

有効: Button、 Combo、 Menu

NoShowOnMenuController このフラグを持つコマンドがメニューコントローラーに配置されている場合、コマンドはドロップダウンリストに表示されません。

有効範囲: Button

コマンドフラグの詳細については、 CommandFlag 要素のドキュメントを参照してください。

一般的な要件

コマンドを表示して有効にするには、次の一連のテストに合格する必要があります。

コマンドは正しく配置されています。
DefaultInvisible フラグが設定されていません。
親メニューまたはツールバーが表示されます。
VisibilityConstraints 要素セクションのコンテキストエントリのため、このコマンドは表示されません。
IOleCommandTarget インターフェイスを実装する VSPackage コードが表示され、コマンドが有効になります。インターフェイスコードがそれをインターセプトして操作したわけではありません。
ユーザーがコマンドをクリックすると、ルーティングアルゴリズムで説明されている手順の対象になります。

定義済みのコマンドを呼び出す

UsedCommands 要素を使用すると、VSPackage は他の VSPackage または IDE によって提供されるコマンドにアクセスできます。これを行うには、使用するコマンドの GUID と ID を持つ UsedCommand 要素を作成します。これにより、現在の Visual Studio 構成に含まれていない場合でも、コマンドが Visual Studio によって読み込まれます。詳細については、「 UsedCommand 要素」を参照してください。

インターフェイス要素の外観

コマンド要素の選択と配置に関する考慮事項は次のとおりです。

Visual Studio には、配置に応じて異なる方法で表示される多くの UI 要素が用意されています。
DefaultInvisible フラグを使用して定義された UI 要素は、QueryStatus メソッドの VSPackage 実装によって表示されるか、VisibilityConstraints セクションで特定の UI コンテキストに関連付けられている場合でない限り、IDE に表示されません。
正常に配置されたコマンドも表示されない場合があります。これは、VSPackage が実装している (または実装していない) インターフェイスに応じて、IDE によって一部のコマンドが自動的に非表示または表示されるためです。たとえば、VSPackage の一部のビルドインターフェイスの実装により、ビルド関連のメニュー項目が自動的に表示されます。
UI 要素の定義に CommandWellOnly フラグを適用することは、カスタマイズによってのみコマンドを追加できることを意味します。
コマンドは、特定の UI コンテキストでのみ使用できます。たとえば、IDE がデザインビューにある場合にのみダイアログボックスが表示されます。
特定の UI 要素を IDE に表示するには、1 つ以上のインターフェイスを実装するか、コードを記述する必要があります。

メニューとコマンドを拡張する

Last updated on 2025-12-12

次の方法で共有

VSPackage でユーザー インターフェイス要素を追加する方法

Visual Studio コマンド テーブルのアーキテクチャ