拡張機能の公開

高品質な拡張機能が完成したら、VS Code 拡張機能マーケットプレースに公開して、他のユーザーがその拡張機能を見つけてダウンロードし、使用できるようにすることができます。または、拡張機能をインストール可能な VSIX 形式にパッケージ化して、他のユーザーと共有することもできます。

このトピックの内容

• VS Code 拡張機能管理用の CLI ツールであるvsceの使用
• 拡張機能のパッケージ化、公開、および非公開化
• 拡張機能を公開するために必要な発行元の登録

vsce

「Visual Studio Code Extensions」の略であるvsceは、VS Code 拡張機能をパッケージ化、公開、管理するためのコマンドラインツールです。

インストール

Node.jsがインストールされていることを確認してください。次に実行します。

npm install -g @vscode/vsce

使用方法

vsceを使用して、拡張機能を簡単にパッケージ化および公開できます。

$ cd myExtension
$ vsce package
# myExtension.vsix generated
$ vsce publish
# <publisher id>.myExtension published to VS Code Marketplace

vsceは、拡張機能の検索、メタデータの取得、非公開化も行うことができます。使用可能なすべてのvsceコマンドのリファレンスについては、vsce --helpを実行してください。

拡張機能の公開

公開ツールは、次の制約をチェックします。

• package.jsonで提供されるアイコンは SVG であってはなりません。
• package.jsonで提供されるバッジは、信頼できるバッジプロバイダーからのものでない限り、SVG であってはなりません。
• README.mdおよびCHANGELOG.mdの画像 URL は、httpsURL に解決される必要があります。
• README.mdおよびCHANGELOG.mdの画像は、信頼できるバッジプロバイダーからのものでない限り、SVG であってはなりません。

Visual Studio Code は、マーケットプレースサービスにAzure DevOpsを使用しています。これは、拡張機能の認証、ホスティング、管理が Azure DevOps を通じて提供されることを意味します。

vsceは個人用アクセス トークンを使用してのみ拡張機能を公開できます。拡張機能を公開するには、少なくとも 1 つ作成する必要があります。

個人用アクセス トークンを取得する

まず、Azure DevOps で独自の組織を作成するためのドキュメントに従ってください。次の例では、組織名はvscodeですが、ご自身の新しい組織名を適切に使用してください。組織名と発行元名が必ずしも同じである必要はないことに注意してください。

1. 組織のホームページ (例: https://dev.azure.com/vscode) から、プロフィール画像の横にあるユーザー設定ドロップダウンメニューを開き、個人用アクセス トークンを選択します。

   

2. 個人用アクセス トークンページで、新しいトークンを選択します。

   

3. 新しい個人用アクセス トークンを作成するモーダルで、トークンについて次の詳細を選択します。

   • 名前: トークンに付けたい任意の名前
   • 組織: アクセス可能なすべての組織
   • 有効期限 (オプション): トークンの希望する有効期限を設定します。
   • スコープ: カスタム定義
     • スコープセクションの下にあるすべてのスコープを表示リンクをクリックします。
     • スコープリストで、Marketplaceまでスクロールし、管理スコープを選択します。

   

4. 作成をクリックします。

   新しく作成された個人用アクセス トークンが表示されます。これを安全な場所にコピーしてください。発行元を作成するために必要になります。

発行元を作成する

発行元とは、Visual Studio Code Marketplace に拡張機能を公開できる ID です。すべての拡張機能は、そのpackage.jsonファイルにpublisher識別子を含める必要があります。

発行元を作成するには

1. Visual Studio Marketplace 発行元管理ページに移動します。

2. 前のセクションで個人用アクセス トークンを作成したのと同じ Microsoft アカウントでログインします。

3. 左側のペインで発行元を作成をクリックします。

4. 新しいページで、新しい発行元の必須パラメーターである識別子と名前 (それぞれIDと名前フィールド) を指定します。

   • ID: 拡張機能の URL で使用される、Marketplace における発行元の一意の識別子。一度作成すると変更できません。
   • 名前: Marketplace で拡張機能とともに表示される、発行元の一意の名前。これは会社名またはブランド名にすることができます。

   以下は、Python 拡張機能の発行元識別子と名前の例です。

   

5. 必要に応じて、残りのフィールドを記入してください。

6. 作成をクリックします。

7. vsceを使用して新しく作成された発行元を確認します。ターミナルで次のコマンドを実行し、プロンプトが表示されたら、前の手順で作成した個人用アクセス トークンを入力します。

   vsce login <publisher id>
   
   https://marketplace.visualstudio.com/manage/publishers/
   Personal Access Token for publisher '<publisher id>': ****************************************************
   
   The Personal Access Token verification succeeded for the publisher '<publisher id>'.
   

確認が完了したら、拡張機能を公開する準備が整いました。

拡張機能を公開する

拡張機能は2つの方法で公開できます。

1. vsce publishコマンドを使用した自動公開

   vsce publish
   

   上記のvsce loginコマンドで個人用アクセス トークンを提供していない場合、vsceはそれを要求します。

2. vsce packageを使用して拡張機能をインストール可能なVSIX形式にパッケージ化し、それをVisual Studio Marketplaceの発行元管理ページにアップロードすることによる手動公開

   

拡張機能のインストールと評価を確認する

Visual Studio Marketplaceの発行元管理ページでは、各拡張機能の経時的な取得傾向、総取得数、評価とレビューにアクセスできます。レポートを表示するには、拡張機能をクリックするか、その他のアクション > レポートを選択します。

拡張機能のバージョンを自動的に増分する

拡張機能を公開する際、SemVer互換の数値またはバージョン（major、minor、またはpatch）を指定することで、バージョン番号を自動的に増分できます。たとえば、拡張機能のバージョンを1.0.0から1.1.0に更新するには、次のように指定します。

vsce publish minor

または

vsce publish 1.1.0

どちらのコマンドも、まず拡張機能のpackage.jsonのversion属性を変更し、次に更新されたバージョンで公開します。

拡張機能の非公開化

Visual Studio Marketplace 発行元管理ページでその他のアクション > 非公開をクリックすると、拡張機能を非公開にできます。

非公開にされると、拡張機能の可用性ステータスは非公開に変更され、マーケットプレースと Visual Studio Code の両方からダウンロードできなくなります。

拡張機能の削除

拡張機能は2つの方法で削除できます。

1. vsceツールとunpublishコマンドを使用した自動削除

   vsce unpublish <publisher id>.<extension name>
   

2. Visual Studio Marketplace 発行元管理ページから、その他のアクション > 削除をクリックすることによる手動削除

   

どちらの場合も、拡張機能名を入力して削除を確認するプロンプトが表示されます。削除操作は元に戻せないことに注意してください。

拡張機能の非推奨化

拡張機能を非推奨にするか、別の拡張機能または設定を推奨する形で非推奨にすることができます。非推奨になった拡張機能は、UI で薄い取り消し線付きのテキストで表示されます。

各非推奨拡張機能のタイル右下隅には、黄色の警告アイコンが表示されます（上記のスクリーンショットを参照）。拡張機能タイルにマウスオーバーすると、このアイコンの横に非推奨の詳細が表示されます。これは、以下のいずれかを示します。

• 拡張機能は代替なしで非推奨になりました

  

• 拡張機能は別の拡張機能に置き換えられました

  

• 拡張機能は設定に置き換えられました

  

VS Codeは、すでにインストールされている非推奨の拡張機能を自動的に移行またはアンインストールしません。非推奨の拡張機能に代替の拡張機能または設定がある場合、VS Codeは指定された代替にすばやく切り替えるのに役立つ移行ボタンを表示します。

拡張機能を非推奨としてマークするには、非推奨の拡張機能ディスカッションスレッドにコメントを残してください。

拡張機能のパッケージ化

次の場合、拡張機能をパッケージ化することを選択できます。

• VS Code インスタンスでテストする。
• マーケットプレースに公開せずに配布する。
• 他の人と非公開で共有する。

パッケージ化とは、拡張機能を含む.vsixファイルを作成することです。このファイルは、VS Code にインストールできます。一部の拡張機能は、GitHub リリースの一部として.vsixファイルを公開しています。

拡張機能をパッケージ化するには、拡張機能のルートフォルダーで次のコマンドを実行します。

vsce package

このコマンドは、拡張機能のルートフォルダーに.vsixファイルを作成します。例えば、my-extension-0.0.1.vsix。

ユーザーがVS Codeに.vsixファイルをインストールするには

• VS Code の拡張機能ビューから

  1. 拡張機能ビューに移動します。
  2. ビューとその他のアクション...を選択します。
  3. VSIX からインストール...を選択します。

• コマンドラインから

  # if you use VS Code
  code --install-extension my-extension-0.0.1.vsix
  
  # if you use VS Code Insiders
  code-insiders --install-extension my-extension-0.0.1.vsix
  

拡張機能フォルダー

拡張機能をロードするには、ファイルをVS Codeの拡張機能フォルダー.vscode/extensionsにコピーする必要があります。オペレーティングシステムによって、このフォルダーの場所は異なります。

• Windows: %USERPROFILE%\.vscode\extensions
• macOS: ~/.vscode/extensions
• Linux: ~/.vscode/extensions

Visual Studio Code の互換性

拡張機能を作成する際は、拡張機能が互換性のある VS Code のバージョンを指定する必要があります。これを行うには、package.json内のengines.vscodeプロパティを使用します。

{
  "engines": {
    "vscode": "^1.8.0"
  }
}

• 1.8.0（キャレットなし）という値は、拡張機能が VS Code 1.8.0とのみ互換性があることを意味します。
• ^1.8.0という値は、拡張機能が VS Code 1.8.0以降（1.8.1、1.9.0などを含む）との互換性があることを意味します。

engines.vscodeプロパティを使用すると、依存する API を含むクライアントにのみ拡張機能がインストールされるようにできます。このメカニズムは、Stable および Insiders リリースでうまく機能します。

たとえば、VS Code の最新の安定版が1.8.0だとします。バージョン1.9.0の開発中に、新しい API が導入され、バージョン1.9.0-insiderを通じて Insider リリースで利用可能になりました。この API の恩恵を受ける拡張機能のバージョンを公開したい場合、バージョン依存関係を^1.9.0と指定する必要があります。これにより、新しい拡張機能バージョンは VS Code >=1.9.0（つまり、現在の Insiders リリースを使用しているユーザー）でのみ利用可能になります。VS Code Stable を使用しているユーザーは、安定版リリースがバージョン1.9.0に達したときにのみ更新を受け取ります。

高度な使用法

マーケットプレースとの統合

Visual Studio Marketplace での拡張機能の外観をカスタマイズできます。例については、Go 拡張機能を参照してください。

マーケットプレースで拡張機能を見栄え良くするためのヒントをいくつかご紹介します。

• 拡張機能のルートにREADME.mdファイルを追加し、拡張機能のマーケットプレースページに表示したいコンテンツを記述します。

  注

  package.jsonに公開GitHubリポジトリを指すrepositoryプロパティがある場合、vsceは自動的にそれを検出し、デフォルトでmainブランチを使用して相対リンクを調整します。これは、vsce packageまたはvsce publishを実行する際に--githubBranchフラグで上書きできます。また、--baseContentUrlおよび--baseImagesUrlフラグを使用して、リンクや画像のベースURLを設定することもできます。

• 拡張機能のライセンスに関する情報が記載されたLICENSEファイルを、拡張機能のルートに追加します。

• 拡張機能の変更履歴に関する情報が記載されたCHANGELOG.mdファイルを、拡張機能のルートに追加します。

• 拡張機能のサポートに関する情報が記載されたSUPPORT.mdファイルを、拡張機能のルートに追加します。

• package.jsonのgalleryBanner.colorプロパティに適切な16進数値を指定して、マーケットプレースページのバナー背景色を設定します。

• package.jsonのiconプロパティを介して、拡張機能に含まれる128x128px以上のPNGファイルへの相対パスを指定してアイコンを設定します。

詳細については、マーケットプレース表示のヒントを参照してください。

発行元を確認する

ブランドまたはIDに関連付けられた対象ドメインの所有権を確認することで、確認済み発行元になることができます。発行元が確認されると、Marketplaceは拡張機能の詳細に確認済みバッジを追加します。

前提条件

確認済みとなるには、発行元がVS Marketplaceに6か月以上1つ以上の拡張機能を持っている必要があり、ドメインの登録も少なくとも6か月前である必要があります。確認を申請する前に、これらの条件が満たされるまでお待ちください。

発行元を確認するには

1. Visual Studio Marketplace 発行元管理ページに移動します。

2. 左側のペインで、確認したい発行元を選択または作成します。

3. メインペインで、詳細タブを選択します。

   

4. 詳細タブの確認済みドメインセクションで、対象ドメインを入力します。

   

   注: 入力を開始すると、詳細タブのタイトルにアスタリスク (*) が表示されます。VS Code と同様に、これは未保存の変更があることを示します。同じ理由で、検証ボタンはまだ無効になっています。

5. 保存を選択し、次に検証を選択します。

   

   ダイアログウィンドウが表示され、ドメインのDNS設定にTXTレコードを追加するための手順が示されます。

   

6. 指示に従って、ドメインのDNS設定にTXTレコードを追加します。

7. ダイアログウィンドウで検証を選択して、TXTレコードが正常に追加されたことを確認します。

   

   TXTレコードが検証されると、Marketplaceチームがお客様のリクエストをレビューし、5営業日以内に結果をお知らせします。検証には、ドメイン、ウェブサイト、拡張機能の実績の前提条件、コンテンツの適格性、正当性、信頼性、肯定的な評価などが含まれますが、これらに限定されません。

検証に合格すると、Visual Studio Marketplace発行元管理ページの発行元名の横に、対応するバッジが表示されます。

注:

• 発行元の表示名の変更は、検証済みバッジを取り消します。
• 発行元が将来の利用規約または上記に記載された検証違反を行った場合、検証済みバッジは取り消されます。

対象となるドメイン

対象となるドメインは、次の基準を満たしています。

• DNS 設定を管理し、TXT レコードを追加できる必要があります。
• サブドメイン（{subdomain}.github.io、{subdomain}.contoso.com など）ではありません。
• HTTPS プロトコルを使用する必要があります。
• HEAD リクエストに対して HTTP 200 ステータスで応答できる必要があります。

拡張機能の価格ラベル

拡張機能のマーケットプレースページに価格ラベルを表示して、無料または無料試用版であることを示すことができます。

価格ラベルを表示するには、pricingプロパティをpackage.jsonに追加します。例えば、

{
  "pricing": "Free"
}

許可される値は、FreeとTrial（大文字小文字を区別）です。pricingプロパティが指定されていない場合、デフォルト値はFreeです。

拡張機能スポンサー

スポンサーシップを選択して、ユーザーがあなたの活動をサポートする方法を提供できます。

スポンサーリンクを表示するには、sponsorプロパティをpackage.jsonに追加します。たとえば、

"sponsor": {
  "url": "https://github.com/sponsors/nvaccess"
}

スポンサーリンクは、マーケットプレースの拡張機能ページと、VS Code の拡張機能詳細ヘッダーに表示されます。

これにより、ユーザーが依存している拡張機能に資金を提供し、拡張機能のパフォーマンス、信頼性、安定性を向上させることができるようになることを願っています。

.vscodeignore の使用

.vscodeignoreファイルを作成して、一部のファイルが拡張機能のパッケージに含まれないようにすることができます。このファイルは、1行に1つのglobパターンが記述されたコレクションです。例えば、

**/*.ts
**/tsconfig.json
!file.ts

実行時に不要なファイルはすべて無視する必要があります。たとえば、拡張機能がTypeScriptで書かれている場合、上記の例のようにすべての**/*.tsファイルを無視する必要があります。

公開前ステップ

マニフェストファイルに公開前ステップを追加できます。これは拡張機能がパッケージ化されるたびに呼び出されます。たとえば、この段階でTypeScriptコンパイラを呼び出すことができます。

{
  "name": "uuid",
  "version": "0.0.1",
  "publisher": "someone",
  "engines": {
    "vscode": "0.10.x"
  },
  "scripts": {
    "vscode:prepublish": "tsc"
  }
}

プレリリース拡張機能

ユーザーはVS CodeまたはVS Code Insidersで拡張機能のプレリリースバージョンをインストールし、公式リリースより前に最新の拡張機能バージョンを定期的に取得できます。

プレリリースバージョンを公開するには、vsce packageまたはvsce publishコマンドに--pre-releaseフラグを渡します。

vsce package --pre-release
vsce publish --pre-release

拡張機能のバージョンはmajor.minor.patchのみをサポートしており、semverプレリリース タグはサポートされていません。プレリリース版と通常リリース版でバージョンは異なる必要があります。つまり、1.2.3がプレリリース版としてアップロードされた場合、次の通常リリース版は1.2.4などの異なるバージョンでアップロードする必要があります。完全なsemverサポートは将来利用可能になる予定です。

VS Codeは拡張機能を自動的に利用可能な最高バージョンに更新するため、ユーザーがプレリリースバージョンを選択し、より高いバージョンの拡張機能リリースがある場合でも、ユーザーはリリースバージョンに更新されます。そのため、拡張機能ではリリースバージョンにはmajor.EVEN_NUMBER.patchを、プレリリースバージョンにはmajor.ODD_NUMBER.patchを使用することをお勧めします。たとえば、リリースには0.2.*、プレリリースには0.3.*です。

拡張機能の作者がプレリリースユーザーをリリースバージョンに更新したくない場合、リリースバージョンを公開する前に常に新しいプレリリースバージョンを増分して公開し、プレリリースバージョンが常に高くなるようにすることをお勧めします。ただし、プレリリースユーザーは、リリースバージョンよりも高いバージョン番号の将来のプレリリースに自動的に更新される資格を保持していることに注意してください。

プレリリース拡張機能は VS Code バージョン1.63.0以降でサポートされているため、すべてのプレリリース拡張機能はpackage.jsonのengines.vscodeの値を>= 1.63.0に設定する必要があります。

プラットフォーム固有の拡張機能

VS Codeが実行されている各プラットフォーム（Windows、Linux、macOS）向けに、拡張機能のVSIXパッケージを公開できます。このような拡張機能をプラットフォーム固有と呼びます。

バージョン1.61.0以降、VS Codeは現在のプラットフォームに一致する拡張機能パッケージを探します。

プラットフォーム固有の拡張機能は、拡張機能にプラットフォーム固有のライブラリや依存関係がある場合に役立ち、プラットフォームパッケージに含まれる正確なバイナリを制御できます。一般的なユースケースは、ネイティブノードモジュールの使用です。

プラットフォーム固有の拡張機能は、プラットフォーム固有のコンテンツを含む個別のパッケージとして公開されます。--targetフラグを渡すことで、ターゲットプラットフォームを指定できます。このフラグを渡さない場合、そのパッケージはプラットフォーム固有のパッケージがないすべてのプラットフォームのフォールバックとして使用されます。

現在利用可能なプラットフォームは、win32-x64、win32-arm64、linux-x64、linux-arm64、linux-armhf、alpine-x64、alpine-arm64、darwin-x64、darwin-arm64、およびwebです。

プラットフォーム固有の拡張機能がWeb 拡張機能としてブラウザで実行されることもサポートしたい場合は、公開時にwebプラットフォームをターゲットにする必要があります。webプラットフォームは、package.jsonのbrowserエントリーポイントを尊重します。webでサポートされていない拡張機能の機能を無効にするには、Web プラットフォーム用に別のpackage.jsonを同梱したり、webで機能しない VSIX の一部を削除したりするのではなく、package.jsonでwhen句を使用することをお勧めします。

公開

バージョン1.99.0以降、vsceはVSIXのパッケージ化および公開中にターゲットプラットフォームを指定できる--targetパラメータをサポートしています。

win32-x64およびwin32-arm64プラットフォーム向けにVSIXを公開する方法は次のとおりです。

vsce publish --target win32-x64 win32-arm64

または、パッケージ化時に--targetフラグを使用してプラットフォーム固有の VSIX を作成することもできます。例えば、win32-x64プラットフォーム用の VSIX をパッケージ化してから公開するには、次のようになります。

vsce package --target win32-x64
vsce publish --packagePath PATH_TO_WIN32X64_VSIX

継続的インテグレーション

複数のプラットフォーム固有の VSIX を管理することは困難になる可能性があるため、継続的インテグレーション (CI) ツールを使用して拡張機能のビルドプロセスを自動化することをお勧めします。たとえば、GitHub Actionsを使用して拡張機能をビルドできます。当社のプラットフォーム固有の拡張機能サンプルは、学習の出発点として使用できます。そのワークフローは、プラットフォーム固有の拡張機能サポートを使用して、ネイティブ ノード モジュールをサポートされているすべての VS Code ターゲットに依存関係として配布する一般的なシナリオを可能にします。

次のステップ

• 拡張機能マーケットプレース - VS Code の公開拡張機能マーケットプレースについてさらに学ぶ。
• 拡張機能のテスト - 高品質を確保するために、拡張機能プロジェクトにテストを追加する。
• 拡張機能のバンドル - webpack で拡張機能ファイルをバンドルして、読み込み時間を改善する。

よくある質問

拡張機能を公開しようとすると、「許容されるタグ数30を超過しました」というエラーが表示されます。

Visual Studio Marketplaceでは、拡張機能パッケージのpackage.jsonに30個を超えるkeywordsを含めることはできません。このエラーを回避するには、キーワード/タグの数を最大30個に制限してください。

拡張機能を公開しようとすると、403 Forbidden（または401 Unauthorized）エラーが表示されます。

PAT（個人用アクセス トークン）を作成する際によくある間違いの1つは、組織フィールドのドロップダウンでアクセス可能なすべての組織ではなく、特定の組織を選択してしまうことです。もう1つの考えられる間違いは、スコープが正しくないことです。公開を機能させるには、承認されたスコープをMarketplace (Manage)に設定する必要があります。

vsceツールから拡張機能を非公開にできません。

拡張機能IDまたは発行元IDを変更した可能性があります。拡張機能は、Visual Studio Marketplace発行元管理ページから直接管理することもできます。例えば、更新または非公開にすることができます。

vsce がファイル属性を保持しないのはなぜですか？

Windows から拡張機能をビルドして公開する場合、拡張機能パッケージに含まれるすべてのファイルには、POSIX ファイル属性、つまり実行可能ビットが欠落していることに注意してください。一部のnode_modules依存関係は、これらの属性に依存して正しく機能します。Linux および macOS からの公開は期待どおりに機能します。

継続的インテグレーション (CI) ビルドから公開できますか？

はい、Azure DevOps、GitHub Actions、および GitLab CI を設定して拡張機能を Marketplace に自動的に公開する方法については、継続的インテグレーショントピックの自動公開セクションを参照してください。

拡張機能を公開しようとすると、「エラー: 拡張機能 'name' はすでに Marketplace に存在します」というエラーが表示されます。

マーケットプレースでは、すべての拡張機能で拡張機能名が一意である必要があります。同じ名前の拡張機能がマーケットプレースにすでに存在する場合、次のエラーが表示されます。

ERROR The extension 'name' already exists in the Marketplace.

拡張機能の表示名にも同じルールが適用されます。

どのパッケージマネージャーがサポートされていますか？

拡張機能の依存関係を管理するには、npmまたはyarn v1を使用できます。

VS Marketplaceアカウントや拡張機能の公開に関するサポートが必要ですか？

発行元と拡張機能の管理にサインインし、右上の「Microsoft に問い合わせる」リンクをクリックすることで、VS Marketplace サポートチームに連絡できます。