vsce - 公開ツールのリファレンス
vsceはExtension Marketplaceに拡張機能を公開するために使用するコマンドラインツールです。拡張機能をローカルに読み込んだりemailやUNCのドライブを経由して共有することもできます。
インストール
Node.jsがインストールされていることを確認します。次に以下を実行します:
|
使い方
コマンドラインから直接vsce
コマンドを使用します。たとえば、拡張機能を素早く公開する方法は次の通りです:
|
使用可能なすべてのコマンドの参考文献は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ページに移動します:
新しいPersonal Access Tokenを作成するにはAddをクリックします。
Personal Access Tokenに説明をつけ、必要に応じて有効期間を1年間に延長し、すべてのアカウントでアクセスできるようにして、権限をall scopesに設定します。
移動先では、新しく作成したPersonal Access Tokenが表示されます。Copyはパブリッシャーを作成するために必要です。
パブリッシャーを作成
パブリッシャーとは、Visual Studio Code Marketplaceに拡張機能を公開できるユーザーのことです。すべての拡張機能は拡張機能のpackage.json
ファイルにpublisher
名が要求されます。
一度Personal Access Tokenを入手すれば、vsce
を利用して新しいパブリッシャーを作成できます。
|
vsce
はパブリッシャーを将来参照できるように、Personal Access Tokenを記憶します。
Note: あるいは、次のセクションで説明するように、https://marketplace.visualstudio.com/manage でパブリッシャーを作成して、vsce
でログインします。
パブリッシャーにログイン
作成済みのパブリッシャーをvsce
で使用するには、次を使用してください:
|
create-publisher
コマンドと同様に、vsce
はPersonal Access Tokenを要求したのち今後のコマンドのためにこれを記憶します。
オプションのパラメータ-p <token>
を使用することで、発行とPersonal Access Tokenの入力を同時に行うこともできます。
|
拡張機能のバージョンの自動インクリメント
公開時にSemVerと一致する値を指定することで、拡張機能のバージョンを更新することができます:major
、minor
、patch
たとえば、拡張機能のバージョンを1.0.0から1.1.0に更新したいなら、minor
を指定します。
|
これにより拡張機能の package.json
で version属性が変更されます。
また、コマンドラインで完全なSemVerを指定することもできます:
|
拡張機能のパッケージング
Marketplaceに拡張機能を公開せずに、拡張機能をパッケージ化することができます。拡張機能は常に.vsix
ファイルへパッケージ化されます。次のようにしてください:
|
この操作は拡張機能を.vsix
ファイルにパッケージ化し、現在のディレクトリーに配置します。.vsix
ファイルはVisual Studio Codeにインストールすることが可能です。詳細はInstall from a VSIXを参照してください。
非公開的に共有する
拡張機能をプライベートで共有したいのであれば、拡張機能のパッケージ化ファイル.vsix
を送ることでできます。
VIsual Studio Codeの互換性
拡張機能を作成するときは、Visual Studio Codeとの互換性を記述する必要があります。これはpackage.json
内のengine.vscode
のフィールドで行うことができます:
|
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パターンで書き込めます。
例えば:
|
実行時に不必要なファイルをすべて無視する必要があります。たとえばTypeScriptで書かれた拡張機能では、**/*.ts
ファイルをすべて無視する必要があります。
Note: devDependencies
に登録されている開発依存関係は自動的に無視されるので、.vscodeignore
ファイルに追加する必要はありません。
公開前のステップ
マニフェストファイルに公開前のステップを追加することが可能です。このコマンドは拡張機能がパッケージ化されるたびに呼び出されます。
|
これにより、拡張機能をパッケージ化するとき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から公開するときは期待通りに動作します。