VSIX 拡張機能スキーマ 2.0 リファレンス

  • [アーティクル]

VSIX 配置マニフェスト ファイルには、VSIX パッケージのコンテンツが記述されます。 ファイル形式は、スキーマによって管理されます。 このスキーマのバージョン 2.0 では、カスタム型および属性の追加がサポートされています。 マニフェストのスキーマは拡張可能です。 マニフェスト ローダーでは、認識されない XML 要素および属性は無視されます。

パッケージ マニフェスト スキーマ

マニフェスト XML ファイルのルート要素は、<PackageManifest> です。 これには、マニフェスト形式のバージョンを示す単一の属性 Version が含まれています。 形式に大きな変更が加えられた場合は、バージョンの形式が変更されます。 この記事では、マニフェスト形式のバージョン 2.0 について説明します。これは、マニフェストで Version 属性を値 Version="2.0" に設定することで指定されます。

PackageManifest 要素

<PackageManifest> ルート要素内では、次の要素を使用できます。

  • <Metadata> - パッケージ自体に関するメタデータと広告情報。 マニフェストに含めることができる Metadata 要素は 1 つだけです。

  • <Installation> - このセクションでは、この拡張機能パッケージをインストールする方法を定義します。これには、インストール先のアプリケーション SKU も含まれます。 マニフェストに含めることができる Installation 要素は 1 つだけです。 マニフェストには Installation 要素が必要です。これがない場合、このパッケージはどの SKU にもインストールされません。

  • <Dependencies> - ここでは、このパッケージの依存関係の省略可能なリストを定義します。

  • <Assets> - このセクションには、このパッケージに含まれるすべての資産が含まれています。 このセクションを使用しない場合、このパッケージではコンテンツが提示されません。

  • <AnyElement>* - マニフェスト スキーマは、他の任意の要素を使用できる十分な柔軟性を備えています。 マニフェスト ローダーで認識されない子要素は、拡張機能マネージャー API で追加の XmlElement オブジェクトとして公開されます。 VSIX 拡張機能では、これらの子要素を使用してマニフェスト ファイルに追加のデータを定義し、Visual Studio で実行されるコードから実行時にアクセスできます。 「Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements」を参照してください。

Metadata 要素

このセクションは、パッケージ、その ID、広告情報に関するメタデータです。 <Metadata> には、次の要素があります。

  • <Identity> - このパッケージの識別情報を定義し、次の属性を含んでいます。

    • Id - この属性は、作成者によって選択されたパッケージの一意の ID である必要があります。 この名前は、CLR 型を名前空間として使用する場合と同じ方法 (Company.Product.Feature.Name) で修飾する必要があります。 Id 属性は 100 文字までに制限されています。

    • Version - このパッケージとそのコンテンツのバージョンを定義します。 この属性は、CLR アセンブリのバージョン管理形式 (Major.Minor.Build.Revision) に従います (1.2.40308.00)。 バージョン番号が大きいパッケージは、パッケージの更新プログラムと見なされ、インストールされている既存のバージョンに上書きインストールできます。

    • Language - この属性は、パッケージの既定の言語であり、このマニフェストのテキスト データに対応します。 この属性は、リソース アセンブリの CLR ロケール コード規則 (en-us、en、fr-fr など) に従います。 neutral を指定すると、任意のバージョンの Visual Studio で実行される言語に依存しない拡張機能を宣言できます。 既定値は neutral です。

    • Publisher - この属性では、このパッケージの発行元 (会社または個人名のいずれか) を識別します。 Publisher 属性は 100 文字までに制限されています。

  • <DisplayName> - この要素では、拡張機能マネージャーの UI に表示されるパッケージのユーザーフレンドリ名を指定します。 DisplayName の内容は 50 文字までに制限されています。

  • <Description> - この省略可能な要素は、拡張機能マネージャーの UI に表示されるパッケージとそのコンテンツの簡単な説明です。 Description の内容には任意のテキストを含めることができますが、使用できる文字数は最大 1000 文字です。

  • <MoreInfo> - この省略可能な要素は、このパッケージの詳しい説明を含むオンライン ページの URL です。 プロトコルは http として指定する必要があります。

  • <License> - この省略可能な要素は、パッケージに含まれているライセンス ファイル (.txt、.rtf) への相対パスです。

  • <ReleaseNotes> - この省略可能な要素は、パッケージ (.txt、.rtf) に含まれているリリース ノート ファイルへの相対パスまたはリリース ノートを表示する Web サイトの URL のいずれかです。

  • <Icon> - この省略可能な要素は、パッケージに含まれているイメージ ファイル (png、bmp、jpeg、ico) への相対パスです。 アイコン イメージは、32 x 32 ピクセルである必要があり (そうでない場合は、そのサイズに縮小されます)、リスト ビュー UI に表示されます。 Icon 要素が指定されていない場合、UI では既定値が使用されます。

  • <PreviewImage> - この省略可能な要素は、パッケージに含まれているイメージ ファイル (png、bmp、jpeg) への相対パスです。 プレビュー イメージは、200 x 200 ピクセルである必要があり、詳細 UI に表示されます。 PreviewImage 要素が指定されていない場合、UI では既定値が使用されます。

  • <Tags> - この省略可能な要素では、検索ヒントに使用される、セミコロンで区切られた追加のテキスト タグをリストします。 Tags 要素は 100 文字までに制限されています。

  • <GettingStartedGuide> - この省略可能な要素は、このパッケージ内の拡張機能またはコンテンツの使用方法に関する情報を含む HTML ファイルへの相対パスまたは Web サイトの URL のいずれかです。 このガイドはインストールの一部として起動されます。

  • <AnyElement>* - マニフェスト スキーマは、他の任意の要素を使用できる十分な柔軟性を備えています。 マニフェスト ローダーで認識されない子要素は、XmlElement オブジェクトのリストとして公開されます。 VSIX 拡張機能では、マニフェスト ファイルでこれらの子要素を使用して追加のデータを定義し、実行時にそれらを列挙できます。

Installation 要素

このセクションでは、この拡張機能パッケージをインストールする方法とインストール先のアプリケーション SKU を定義します。 このセクションには、次の属性があります。

  • Experimental - 現在すべてのユーザーに対して拡張機能がインストールされているが、同じコンピューターで更新されたバージョンを開発する場合は、この属性を true に設定します。 たとえば、すべてのユーザーに対して MyExtension 1.0 がインストールされているが、同じコンピューターで MyExtension 2.0 をデバッグする場合は、Experimental="true" に設定します。 この属性は、Visual Studio 2015 Update 1 以降で使用できます。

  • Scope - この属性には、値 "Global" または "ProductExtension" を指定できます。

    • "Global" では、インストールの範囲が特定の SKU に限定されないことを指定します。 たとえば、この値は拡張機能 SDK をインストールするときに使用されます。

    • "ProductExtension" では、従来の VSIX 拡張機能 (バージョン 1.0) を個別の Visual Studio SKU に範囲を限定してインストールすることを指定します。 これが既定値です。

  • AllUsers - この省略可能な属性では、このパッケージをすべてのユーザーに対してインストールするかどうかを指定します。 既定では、この属性はパッケージがユーザー単位であることを指定する false です。 (この値を true に設定した場合、インストールするユーザーは、結果として得られる VSIX をインストールするために管理特権レベルに昇格する必要があります。

  • InstalledByMsi - この省略可能な属性では、このパッケージが MSI によってインストールされるかどうかを指定します。 MSI によってインストールされるパッケージは、Visual Studio 拡張機能マネージャーではなく、MSI ([プログラムと機能]) によってインストールおよび管理されます。 既定では、この属性はパッケージが MSI によってインストールされないことを指定する false です。

  • SystemComponent - この省略可能な属性では、このパッケージをシステム コンポーネントと見なす必要があるかどうかを指定します。 システム コンポーネントは、拡張機能マネージャーの UI に表示されないため、更新できません。 既定では、この属性はパッケージがシステム コンポーネントではないことを指定する false です。

  • AnyAttribute* - Installation 要素では、名前と値のペアのディクショナリとして実行時に公開される無制限の属性セットを受け入れます。

  • <InstallationTarget> - この要素では、VSIX インストーラーでパッケージをインストールする場所を制御します。 Scope 属性の値が "ProductExtension" の場合、パッケージのターゲットは、その可用性を拡張機能に提供するためにそのコンテンツの一部としてマニフェスト ファイルがインストールされている SKU である必要があります。 Scope 属性の値が明示的な (または既定の) "ProductExtension" である場合、<InstallationTarget> 要素には次の属性が含まれます。

    • Id - この属性では、パッケージを識別します。 属性は、名前空間規則 (Company.Product.Feature.Name) に従います。 Id 属性に使用できるのは英数字のみで、100 文字までに制限されています。 期待される値:

      • Microsoft.VisualStudio.IntegratedShell

      • Microsoft.VisualStudio.Pro

      • Microsoft.VisualStudio.Premium

      • Microsoft.VisualStudio.Ultimate

      • Microsoft.VisualStudio.VWDExpress

      • Microsoft.VisualStudio.VPDExpress

      • Microsoft.VisualStudio.VSWinExpress

      • Microsoft.VisualStudio.VSLS

      • My.Shell.App

    • Version - この属性では、この SKU のサポートされる最小および最大バージョンを含むバージョン範囲を指定します。 パッケージでは、サポートされる SKU のバージョンの詳細を示すことができます。 バージョン範囲の表記は [10.0-11.0] です。ここで

      • [ - 最小バージョン (その値を含む)。

      • ] - 最大バージョン (その値を含む)。

      • ( - 最小バージョン (その値を含まない)。

      • ) - 最大バージョン (その値を含まない)。

      • 単一のバージョン番号 - 指定されたバージョンのみ。

      重要

      Visual Studio 2012 で VSIX スキーマのバージョン 2.0 が導入されました。 このスキーマを使用するには、コンピューターに Visual Studio 2012 以降がインストールされていて、その製品の一部である VSIXInstaller.exe を使用する必要があります。 Visual Studio 2012 以降の VSIXInstaller では以前のバージョンの Visual Studio をターゲットにできますが、新しいバージョンのインストーラーを使用する必要があります。

      Visual Studio 2017 のバージョン番号については、「Visual Studio のビルド番号とリリース日」を参照してください。

      Visual Studio 2017 リリースのバージョンを表現する場合、マイナー バージョンは常に 0 にする必要があります。 たとえば、Visual Studio 2017 バージョン 15.3.26730.0 は、[15.0.26730.0,16.0) と表現する必要があります。 これは、Visual Studio 2017 以降のバージョン番号にのみ必要です。

    • AnyAttribute* - <InstallationTarget> 要素では、名前と値のペアのディクショナリとして実行時に公開される無制限の属性セットを使用できます。

Dependencies 要素

この要素には、このパッケージで宣言する依存関係のリストが含まれています。 依存関係が指定されている場合は、(Id によって識別される) それらのパッケージが先にインストールされている必要があります。

  • <Dependency> 要素 - この子要素には、次の属性があります。

    • Id - この属性は、依存パッケージの一意の ID である必要があります。 この ID 値は、このパッケージが依存しているパッケージの <Metadata><Identity>Id 属性と一致している必要があります。 Id 属性は、名前空間規則 (Company.Product.Feature.Name) に従います。 この属性に使用できるのは英数字のみで、100 文字までに制限されています。

    • Version - この属性では、この SKU のサポートされる最小および最大バージョンを含むバージョン範囲を指定します。 パッケージでは、サポートされる SKU のバージョンの詳細を示すことができます。 バージョン範囲の表記は [12.0, 13.0] です。ここで:

      • [ - 最小バージョン (その値を含む)。

      • ] - 最大バージョン (その値を含む)。

      • ( - 最小バージョン (その値を含まない)。

      • ) - 最大バージョン (その値を含まない)。

      • 単一のバージョン番号 - 指定されたバージョンのみ。

    • DisplayName - この属性は、ダイアログ ボックスやエラーメッセージなどの UI 要素で使用される依存パッケージの表示名です。 依存パッケージが MSI によってインストールされる場合を除き、この属性は省略可能です。

    • Location - この省略可能な属性では、この VSIX 内で入れ子になった VSIX パッケージへの相対パスまたは依存関係のダウンロード先の URL のいずれかを指定します。 この属性は、ユーザーが前提条件となるパッケージを見つけやすくするために使用されます。

    • AnyAttribute* - Dependency 要素では、名前と値のペアのディクショナリとして実行時に公開される無制限の属性セットを受け入れます。

Assets 要素

この要素には、このパッケージによって提示される各拡張機能またはコンテンツ要素の <Asset> タグのリストが含まれています。

  • <Asset> - この要素には、次の属性と要素が含まれています。

    • Type - この要素によって表される拡張機能またはコンテンツの種類。 各 <Asset> 要素に 1 つの Type を含める必要がありますが、複数の <Asset> 要素に同じ Type を含めることもできます。 この属性は、名前空間規則に従って完全修飾名として表す必要があります。 既知の種類は次のとおりです。

      1. Microsoft.VisualStudio.VsPackage

      2. Microsoft.VisualStudio.MefComponent

      3. Microsoft.VisualStudio.ToolboxControl

      4. Microsoft.VisualStudio.Samples

      5. Microsoft.VisualStudio.ProjectTemplate

      6. Microsoft.VisualStudio.ItemTemplate

      7. Microsoft.VisualStudio.Assembly

        独自の種類を作成し、一意の名前を指定できます。 Visual Studio 内での実行時に、コードで拡張機能マネージャー API を使用して、これらのカスタムの種類を列挙し、それらにアクセスできます。

    • Path - この資産を含むパッケージ内のファイルまたはフォルダーへの相対パス。

    • TargetVersion - 指定された資産が適用されるバージョン範囲。 複数のバージョンの資産を異なるバージョンの Visual Studio に配布するために使用されます。 Visual Studio 2017.3 以降が有効になっている必要があります。

    • AnyAttribute* - 名前と値のペアのディクショナリとして実行時に公開される無制限の属性セット。

      <AnyElement>* - <Asset> の開始および終了タグの間には、任意の構造化されたコンテンツを含めることができます。 すべての要素は、XmlElement オブジェクトのリストとして公開されます。 VSIX 拡張機能では、マニフェスト ファイルで構造化された種類固有のメタデータを定義し、実行時にそれらを列挙できます。

拡張マニフェストのプレースホルダー構文

このファイルは .vsixmanifest 、VSIX パッケージのビルドを定義します。 ビルドが要求されると、Visual Studio によってマニフェストが解析され、MSBuild を使用して ビルドされるビルド スクリプトが生成されます。 VSIX パッケージがビルドされる前に評価されるプレースホルダーを使用して、ビルド時に特定の値を設定できます。 プレースホルダーは、VSIX プロジェクトで参照されるプロジェクト、MSBuild プロパティ、および MSBuild ターゲット (最も一般的には、プロジェクト出力グループを表すターゲット) を参照するために使用されます。 プロジェクト出力グループは、プロジェクトに関連付けられているファイルのコレクションを表し、これらの一部を VSIX パッケージに含めることができます。 たとえば、「PkgDefProjectOutputGroup」、「BuiltProjectOutputGroup」、「SatelliteDllsProjectOutputGroup」のように指定します。

VSIX プロジェクトで定義されているプロパティを参照するには、プロジェクト ファイル自体 $(PropertyName)と同じ構文を使用します。

特殊なトークン %CurrentProject% は VSIX プロジェクトを参照します。 パイプ 記号 (|) で囲まれた VSIX プロジェクト ファイル内の要素をProjectReference使用してName、VSIX プロジェクトで参照されている他のプロジェクトを参照できます。 たとえば、|ProjectTemplate1| のようにします。

MSBuild ターゲットは、プロジェクトの名前 ( Name VSIX プロジェクトのプロジェクト参照のプロパティ) とターゲット名で参照できます。 たとえば、VSIX パッケージで参照されているプロジェクトのいずれかでターゲットを参照 Version するには、構文 |ProjectName;Version|を使用します。 ターゲットには、 Outputs 使用されるコンテキストに一致する値が必要です。VSIX マニフェストには、文字列値と項目コレクションの置換が適切な場所が含まれています。 たとえば、マニフェストの Version 文字列は次のように置き換えられます。

<Identity Id="0000000-0000-0000-0000-000000000000" Version="|%CurrentProject%;GetVsixVersion|" Language="en-US" Publisher="Company" />

その場合、単純な文字列を GetVsixVersion 返すターゲットが VSIX プロジェクトに存在する必要があります。 たとえば、 にします。

<Target Name="GetVsixVersion" Outputs="$(_VsixVersion)">
  <PropertyGroup>
     <_VsixVersion>1.2.3.4</_VsixVersion>
  </PropertyGroup>
</Target>

プレースホルダーは、SDK スタイルの VSIX プロジェクトで正しい VSIX マニフェスト ファイルを作成するために使用されます。 "TargetFramework" プロパティで Visual Studio のターゲット バージョンを指定するとします。

  • <TargetFramework>vs17.0</TargetFramework> // Target Visual Studio 2022 version 17.0
  • <TargetFramework>vs16.10</TargetFramework> // Target Visual Studio 2019 version 16.10

VSIX ビルドは、ターゲット フレームワークに基づいて、拡張機能マニフェスト ファイルで定義されている値を次のように変換します。 マニフェスト ファイル内の次の構文の場合:

<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="|%CurrentProject%;GetInstallationTargetVersion|" />

VSIX プロジェクト MSBuild コードで使用される出力は次のとおりです。

    <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0, 18.0)">
      <ProductArchitecture>amd64</ProductArchitecture>
    </InstallationTarget>

また、拡張機能マニフェスト内の次のコードの場合は、次のようになります。

 <Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="|%CurrentProject%;GetPrerequisiteTargetVersion|" DisplayName="Visual Studio core editor" />

プロジェクトのビルド コードは次のとおりです。

<Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[17.0, 18.0)" DisplayName="Visual Studio core editor" />

この機能は、プロジェクト参照の名前と MSBuild ターゲットの名前をセミコロンで区切ってプロジェクト出力グループを参照するために Visual Studio によって生成される VSIX マニフェスト ファイルでも使用されます。 たとえば、文字列 |%CurrentProject%;PkgDefProjectOutputGroup| は、現在の VSIX プロジェクトに関連付けられているファイルを .pkgdef 参照する PkgDef 出力グループを意味します。 システム ビルド ファイル Microsoft.Common.CurrentVersion.targets で定義されているターゲットのProjectOutputGroup一部は、Visual Studio によって生成された VSIX マニフェストで使用されます。 VSIX プロジェクトで使用できる追加のプロジェクト出力グループ ターゲットは、Microsoft.VsSDK.targets で定義されています。 次の表に、定義されているプロジェクト出力グループを示します。

ProjectOutputGroup 説明
BuiltProjectOutputGroup ビルド出力を表すファイル。
ContentFilesProjectOutputGroup プロジェクトに関連付けられている非バイナリ ファイル (HTML ファイルや CSS ファイルなど)。
DebugSymbolsProjectOutputGroup Visual Studio の実験用インスタンスで拡張機能をデバッグするためのシンボル ファイル (.pdb) です。
DocumentationFilesProjectOutputGroup XML ドキュメント ファイル。
PkgDefProjectOutputGroup パッケージ定義 (.pkgdef) ファイル。
PriFilesOutputGroup .pri UWP プロジェクトに関連付けられているリソース ファイル。
SatelliteDllsProjectOutputGroup ローカライズされたリソースのサテライト アセンブリ。
SDKRedistOutputGroup プロジェクトによって参照される SDK の再頒布可能フォルダー。
SGenFilesOutputGroup GenerateSerializationAssemblies ファイル。GenerateSerializationAssemblies ターゲットとタスクによって生成されます。
SourceFilesProjectOutputGroup ソース コード ファイル。
TemplateProjectOutputGroup プロジェクト テンプレート。

ビルド システムは、既定のビルド ロジックに従って、これらの出力グループに適切なファイルを設定します。 カスタム ビルドでは、ターゲットの属性を上記のいずれかのターゲットに設定 BeforeTargets することで、プロジェクト出力グループに項目を追加できます。ターゲットでは、タスクを使用 BuiltProjectOutputGroupKeyOutput して出力を設定する方法の例として、上記のターゲットのコードに従います。

高度なシナリオでは、ビルド ターゲットを参照したり、呼び出すカスタム ターゲットを定義したり、ここで説明する構文を使用して VSIX マニフェスト内の任意の要素の値を挿入したりできます。 ターゲットには、使用されるコンテキストの期待に一致する適切な出力パラメーターが必要です。 プロジェクトのビルド出力などのファイルのコレクションが必要な場合は、必要な MSBuild 項目 を出力するターゲットが必要です。 以前にメンションしたプロジェクト出力グループのビルド ターゲットは、独自のターゲットを構築するときに例として使用できます。

サンプル マニフェスト

<?xml version="1.0" encoding="utf-8"?>
<PackageManifest Version="2.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011" xmlns:d="http://schemas.microsoft.com/developer/vsx-schema-design/2011">
  <Metadata>
    <Identity Id="0000000-0000-0000-0000-000000000000" Version="1.0" Language="en-US" Publisher="Company" />
    <DisplayName>Test Package</DisplayName>
    <Description>Information about my package</Description>
    <MoreInfo>http://www.fabrikam.com/Extension1/</MoreInfo>
    <License>eula.rtf</License>
    <ReleaseNotes>notes.txt</ReleaseNotes>
    <Icon>Images\icon.png</Icon>
    <PreviewImage>Images\preview.png</PreviewImage>
  </Metadata>
  <Installation InstalledByMsi="false" AllUsers="false" SystemComponent="false" Scope="ProductExtension">
    <InstallationTarget Id="Microsoft.VisualStudio.Pro" Version="[11.0, 12.0]" />
  </Installation>
  <Dependencies>
    <Dependency Id="Microsoft.Framework.NDP" DisplayName="Microsoft .NET Framework" d:Source="Manual" Version="[4.5,)" />
    <Dependency Id="Microsoft.VisualStudio.MPF.12.0" DisplayName="Visual Studio MPF 12.0" d:Source="Installed" Version="[12.0]" />
  </Dependencies>
  <Assets>
    <Asset Type="Microsoft.VisualStudio.VsPackage" d:Source="Project" d:ProjectName="%CurrentProject%" Path="|%CurrentProject%;PkgdefProjectOutputGroup|" />
  </Assets>
</PackageManifest>

関連項目