拡張機能の公開

vsce - 公開ツールのリファレンス

vsceはExtension Marketplaceに拡張機能を公開するために使用するコマンドラインツールです。拡張機能をローカルに読み込んだりemailやUNCのドライブを経由して共有することもできます。

インストール

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

npm install -g vsce

使い方

コマンドラインから直接vsceコマンドを使用します。たとえば、拡張機能を素早く公開する方法は次の通りです:

$ vsce publish
Publishing uuid@0.0.1...
Successfully published uuid@0.0.1!

使用可能なすべてのコマンドの参考文献はvsce --helpを実行して入手できます。

Visual Studio Codeでは、MarketplaceのサービスにVisual Studio Team Servicesを活用します。つまり、拡張機能の認証、ホスティング、管理はこれを通じて提供されます。

vsceはPersonal Access Tokensを使用してのみ拡張機能を公開できます。拡張機能を公開するには少なくとこれを1つ作成する必要があります。

Personal Access Tokenを入手

まず、Visual Studio Team Servicesアカウントを持っていることを確認します。

次の例でアカウントの名前はmonacotoolsです。アカウントのホームページから(例: https://monacotools.visualstudio.com)、Securityページに移動します:

Security page

新しいPersonal Access Tokenを作成するにはAddをクリックします。

Add personal access token

Personal Access Tokenに説明をつけ、必要に応じて有効期間を1年間に延長し、すべてのアカウントでアクセスできるようにして、権限をall scopesに設定します。

Personal access token details

移動先では、新しく作成したPersonal Access Tokenが表示されます。Copyはパブリッシャーを作成するために必要です。

パブリッシャーを作成

パブリッシャーとは、Visual Studio Code Marketplaceに拡張機能を公開できるユーザーのことです。すべての拡張機能は拡張機能のpackage.json ファイルにpublisher名が要求されます。

一度Personal Access Tokenを入手すれば、vsceを利用して新しいパブリッシャーを作成できます。

vsce create-publisher (publisher name)

vsceはパブリッシャーを将来参照できるように、Personal Access Tokenを記憶します。

Note: あるいは、次のセクションで説明するように、https://marketplace.visualstudio.com/manage でパブリッシャーを作成して、vsceでログインします。

パブリッシャーにログイン

作成済みのパブリッシャーをvsceで使用するには、次を使用してください:

vsce login (publisher name)

create-publisherコマンドと同様に、vsceはPersonal Access Tokenを要求したのち今後のコマンドのためにこれを記憶します。

オプションのパラメータ-p <token>を使用することで、発行とPersonal Access Tokenの入力を同時に行うこともできます。

vsce publish -p <token>

拡張機能のバージョンの自動インクリメント

公開時にSemVerと一致する値を指定することで、拡張機能のバージョンを更新することができます:major、minor、patch

たとえば、拡張機能のバージョンを1.0.0から1.1.0に更新したいなら、minorを指定します。

vsce publish minor

これにより拡張機能の package.jsonで version属性が変更されます。

また、コマンドラインで完全なSemVerを指定することもできます:

vsce publish 2.0.1

拡張機能のパッケージング

Marketplaceに拡張機能を公開せずに、拡張機能をパッケージ化することができます。拡張機能は常に.vsixファイルへパッケージ化されます。次のようにしてください:

vsce package

この操作は拡張機能を.vsixファイルにパッケージ化し、現在のディレクトリーに配置します。.vsixファイルはVisual Studio Codeにインストールすることが可能です。詳細はInstall from a VSIXを参照してください。

非公開的に共有する

拡張機能をプライベートで共有したいのであれば、拡張機能のパッケージ化ファイル.vsixを送ることでできます。

VIsual Studio Codeの互換性

拡張機能を作成するときは、Visual Studio Codeとの互換性を記述する必要があります。これはpackage.json内のengine.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を含むということです。

engine.vscodeフィールドを使用することで、依存するAPIに合わせて拡張機能がインストールされるようにすることができます。この仕組みは、安定版リリースとInsiderで機能します。

たとえばVS Codeの最新の安定版が1.8.0で、1.9.0の開発中に新しいAPIが導入されたInsiderリリースの1.9.0-insiderで利用可能になったとします。このAPIの恩恵を受けるバージョンを拡張機能で公開するには、バージョンの依存性を^1.9.0で示す必要があります・新しい拡張機能はVS Code1.9.0以上にのみインストールされます。つまり現在のすべてのInsiderユーザーはこれを入手でき、安定版のユーザーはバージョンが1.9.0になったときに更新を入手します。

高度な使い方

Marketplaceの統合

Visual Studio Marketplaceで拡張機能の見た目をカスタマイズすることができます。例についてはGo extensionを参照してください。

Marketplace上の拡張機能の見栄えをよくするヒントをいくつか紹介します:

拡張機能のルートにあるREADME.mdファイルを利用して、Marketplaceページの内容を入力します。vsceはREADMEのリンクを2通りの方法で変更できます:
- package.jsonにGitHubの公開リポジトリのrepositoryフィールドを追加すると、vsceはこれを自動的に検出しそれに応じてリンクを調整します。
- vsce packageを実行しているとき--baseContentUrlと--baseImagesUrlフラグを使用することで、動作を上書きしたり設定したりすることができます。次に、パッケージ化された.vsixファイルをvsce publishの引数として拡張機能に渡して拡張機能を公開します。
拡張機能のルートにあるLICENSEファイルはライセンスの内容として使用されます。
拡張機能のルートにあるCHANGELOG.mdファイルは変更履歴の内容として使用されます。
package.jsonのgalleryBanner.colorに16進数を設定することでバナーの背景色を設定できます。
iconをpackage.jsonの128pxのPNGファイルへの相対パスに設定することで、アイコンを設定できます。

またMarketplace Presentation Tipsも参照してください。

`.vscodeignore`

.vscodeignoreファイルを作成して、拡張機能のパッケージからファイルを除外することができます。このファイルでは各行ごとにglobパターンで書き込めます。

例えば:

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

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

Note: devDependencies に登録されている開発依存関係は自動的に無視されるので、.vscodeignoreファイルに追加する必要はありません。

公開前のステップ

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

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

これにより、拡張機能をパッケージ化するときTypeScriptコンパイラーが呼び出されます。

次のステップ

Extension Marketplace - Learn more about VS Code’s public extension Marketplace.
Testing Extensions - Add tests to your extension project to ensure high quality.

よくある質問

Q: 拡張機能を公開しようとすると403 Forbidden(または401 Unauthorized)エラーがでます。

A: PAT(Personal Access Token)を作成するときに間違えやすいものとして、アカウントフィールドのドロップダウンでall accessible accountsを選択しないことです。またAuthorizedスコープをAll scopesに設定して、拡張機能が公開されるようにする必要があります。

Q: vsceツールで発行を取り下げることができません。

A: extension IDもしくはパブリッシャーの名前を変更した可能性があります。またツールを使用しなくても、Marketplaceの管理ページで直接拡張機能を管理することができます。パブリッシャーの管理ページからは拡張機能のアップデートや公開の解除が行えます。

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

A: Windowsから拡張機能をビルドして公開する場合、拡張機能のパッケージに含まれるすべてのファイルにPOSIX属性、つまりexecutable bit(実行ビット?)がないことに注意する必要があります。いくつかのnode_modules依存関係は正しく機能させるためにこれらの属性を当てにします。LinuxとOS Xから公開するときは期待通りに動作します。