VS Code 拡張機能開発ガイド

Visual Studio Code (VS Code) の拡張機能の作り方をステップバイステップで解説するガイドブックです。

章構成

1. はじめに

VS Code 拡張機能の概要と、開発を始めるための前提環境について説明します。
2. 開発環境のセットアップ

Yeoman ジェネレータを使用したプロジェクトの自動生成と、作成されたプロジェクトのフォルダ構成について説明します。
3. 最初の拡張機能開発

Hello World コマンドの作成、拡張機能のデバッグ実行、基本的な API の使い方を学びます。
4. 主要な機能とAPI

アクティベーションイベント、コントリビューションポイント、主要な UI コンポーネントの実装方法を学びます。
5. パッケージ化と公開

vsce ツールを使用した拡張機能のパッケージ化（VSIX）と、VS Code Marketplace への公開手順を説明します。
6. まとめと参考リソース

開発に役立つ公式ドキュメントやサンプルコード集などの参考リソースをまとめます。

1. はじめに

VS Code 拡張機能とは

VS Code 拡張機能（Extension）は、Visual Studio Code の機能を拡張するためのプログラムです。拡張機能を追加することで、標準機能にはない様々な機能をエディタに追加できます。たとえば、特定のプログラミング言語の構文ハイライト、コード補完、デバッグ機能の連携、操作を便利にするコマンドの追加、エディタ全体の見た目を変えるテーマ設定などが可能です。

VS Code は最初から非常に軽量なエディタとして設計されており、高度な機能の多くは拡張機能の仕組みによって実現されています。開発者は JavaScript または TypeScript を使用して、VS Code が提供する豊富な API を呼び出すことで、エディタの動作をほぼ自由に制御できます。

開発に必要な前提環境

VS Code 拡張機能を開発するには、あらかじめ以下のツールをコンピュータにインストールしておく必要があります。

Node.js

拡張機能のビルドや依存ライブラリの管理、ジェネレータの実行に必要です。LTS（推奨版）の最新バージョンをインストールしてください。
npm (Node Package Manager)

ライブラリをインストールするためのパッケージ管理ツールです。Node.js に同梱されています。
Git

プロジェクトのバージョン管理や、拡張機能を作成するツールの実行時に必要になる場合があります。
Visual Studio Code

作成した拡張機能を実際に動かしてテストするために必要です。

これらのツールが正しくインストールされているかは、コマンドプロンプトやターミナルで node -v や npm -v を実行してバージョンが表示されることで確認できます。

2. 開発環境のセットアップ

Yeoman ジェネレータによるプロジェクト生成

VS Code 拡張機能のプロジェクトは、公式が提供する Yeoman ジェネレータ（yo）と拡張機能用テンプレート（generator-code）を使用することで簡単に初期作成できます。これらは npm コマンドを使用して、コマンドプロンプトやターミナルから一時的に実行できます。

まず、以下のコマンドを実行してジェネレータを起動します。

npx -y yo generator-code

実行すると、コマンドライン上で対話的な質問が始まります。以下の指示に従って選択または入力してください。

What type of extension do you want to create?

New Extension (TypeScript) を選択します（型定義がある TypeScript が書きやすいため推奨されます）。
What’s the name of your extension?

拡張機能の表示名を入力します（例: My First Extension）。
What’s the identifier of your extension?

識別子を入力します。エンターキーを押すと、名前をベースに自動で決定されます（例: my-first-extension）。
What’s the description of your extension?

拡張機能の説明を簡単に書きます（空欄のままエンターキーを押しても構いません）。
Initialize a git repository?

Git リポジトリを初期化するかどうかです。必要に応じて Yes または No を選択します。
Bundle the source code with webpack?

ビルドに Webpack を使用するかどうかです。今回はシンプルな構成にするため No を選択します。
Which package manager to use?

パッケージマネージャを選択します。ここでは npm を選択します。

質問にすべて答えると、必要なファイルが自動的に生成され、依存パッケージのインストールが始まります。

プロジェクトのフォルダ構成

作成されたフォルダを VS Code で開くと、以下のようなファイルとフォルダの構成になっています。主要なファイルの役割は以下の通りです。

package.json

拡張機能の設定ファイルです。名前やバージョン、拡張機能が実行されるトリガー（activationEvents）、VS Code に追加するコマンド（contributes.commands）などを定義します。
src/extension.ts

拡張機能のメインプログラムです。拡張機能が読み込まれたときに呼び出される activate 関数や、終了時に呼び出される deactivate 関数が記述されています。
vsc-extension-quickstart.md

開発の始め方やデバッグ方法が書かれた公式のクイックスタートガイドです。
.vscode/launch.json

拡張機能をデバッグ実行するための設定ファイルです。これがあることで、F5 キーを押すだけでデバッグ用の VS Code が自動的に起動します。

3. 最初の拡張機能開発

Hello World コマンドの作成と動作確認

ジェネレータで生成されたプロジェクトには、最初から「Hello World」を表示するサンプルコードが含まれています。このサンプルコードを使って、拡張機能がどのように起動され、動作するのかを確認します。

まず、生成されたプロジェクトフォルダを VS Code で開きます。次に、キーボードの F5 キーを押すか、左側のアクティビティバーにあるデバッグアイコンをクリックし、上部の実行ボタン（緑色の三角マーク）を押します。

デバッグが開始されると、自動的に新しい VS Code のウィンドウ（「[Extension Development Host]」という名前のウィンドウ）が起動します。このウィンドウには、開発中の拡張機能があらかじめインストールされた状態になっています。

起動したウィンドウで、以下の操作を行ってください。

コマンドパレットを開きます（Windows/Linux: Ctrl + Shift + P、macOS: Cmd + Shift + P）。
「Hello World」と入力し、候補に表示される Hello World コマンドを選択して実行します。
ウィンドウの右下に「Hello World from My First Extension!」というメッセージボックスが表示されます。

メッセージが表示されたら、拡張機能の動作確認は完了です。デバッグを停止するには、元の VS Code ウィンドウの上部に表示されているデバッグツールバーの「停止」ボタン（赤い四角マーク）を押します。

基本的な API の使用方法

それでは、拡張機能がどのように動いているか、プログラムコードを見てみましょう。 src/extension.ts を開きます。

主要なコード部分は以下のようになっています。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('Congratulations, your extension "my-first-extension" is now active!');

    const disposable = vscode.commands.registerCommand('my-first-extension.helloWorld', () => {
        vscode.window.showInformationMessage('Hello World from My First Extension!');
    });

    context.subscriptions.push(disposable);
}

export function deactivate() {}

主要な関数の役割は以下の通りです。

import * as vscode from ‘vscode’

VS Code が提供する API を利用するためのライブラリをインポートしています。
activate(context)

拡張機能が有効化されたときに一度だけ呼び出される関数です。ここでコマンドの登録などを行います。 vscode.commands.registerCommand を使って、コマンド ID（my-first-extension.helloWorld）と、それが実行されたときに実行する処理（メッセージ表示など）を紐付けています。
deactivate()

拡張機能がクリーンアップまたは無効化されるときに呼び出される関数です。リソースの解放が必要な場合はここに記述します。

このように、API を呼び出してエディタの機能を操作するのが、VS Code 拡張機能開発の基本となります。

4. 主要な機能とAPI

アクティベーションイベント（activationEvents）

アクティベーションイベントは、拡張機能がメモリに読み込まれる（有効化される）トリガーとなる条件を定義するものです。 VS Code は、起動速度の低下やメモリの無駄遣いを防ぐため、必要になるまで拡張機能を読み込みません。この遅延読み込みのタイミングを制御するのが activationEvents です。

設定は package.json に記述します。

{
  "activationEvents": [
    "onCommand:my-first-extension.helloWorld"
  ]
}

代表的なアクティベーションイベントには以下のようなものがあります。

onCommand:…

特定のコマンドが実行されたときに拡張機能を有効化します。
onLanguage:…

特定のプログラミング言語のファイル（例: onLanguage:typescript）が開かれたときに有効化します。
onFileSystem:…

特定のファイルシステム上のファイルが読み込まれたときに有効化します。
*

VS Code が起動した直後に、無条件で有効化します。起動速度に影響するため、どうしても必要な場合以外は使用を避けるべきです。

コントリビューションポイント（contributes）

コントリビューションポイントは、拡張機能が VS Code に対して提供する「機能の宣言」です。これにより、プログラムを実行することなく、VS Code の UI（メニュー、サイドバー、キーボードショートカットなど）に項目を追加できます。

設定は package.json の contributes フィールドに記述します。

{
  "contributes": {
    "commands": [
      {
        "command": "my-first-extension.helloWorld",
        "title": "Hello World"
      }
    ],
    "menus": {
      "editor/context": [
        {
          "command": "my-first-extension.helloWorld",
          "group": "navigation"
        }
      ]
    }
  }
}

上記の例では、以下の2つを登録しています。

commands

コマンドパレットに表示されるコマンド ID とタイトルを定義します。
menus

エディタ上で右クリックしたときに表示されるコンテキストメニュー（editor/context）に、登録したコマンドを追加します。

主要な UI コンポーネントの実装

VS Code の API を使用することで、様々な UI コンポーネントを表示・操作できます。

ステータスバー (StatusBar)

エディタ最下部のステータスバーに、テキストやアイコンを表示できます。 vscode.window.createStatusBarItem を使用して作成します。
ツリービュー (Tree View)

サイドバーの領域に独自の階層メニューを表示できます。エクスプローラーのようにプロジェクト内のリソースを表示するのに適しています。 vscode.window.registerTreeDataProvider を使用して実装します。
ウェブビュー (Webview)

HTML、CSS、JavaScript を使用して、VS Code 内に完全に自由なデザインの Web ページを表示する機能です。 vscode.window.createWebviewPanel を使用して、カスタムのエディタやダッシュボード画面を作成できます。

5. パッケージ化と公開

`vsce` によるパッケージ化（.vsix ファイルの作成）

開発した拡張機能を他の人に配布したり、自分自身で日常的に使ったりするために、拡張機能をパッケージ化して .vsix ファイルを作成します。パッケージ化には、VS Code 拡張機能公式の CLI ツールである @vscode/vsce を使用します。

まず、以下のコマンドを実行してツールをグローバルにインストールします。

npm install -g @vscode/vsce

次に、拡張機能のプロジェクトルートディレクトリに移動し、以下のパッケージコマンドを実行します。

vsce package

コマンドを実行すると、プロジェクトルートに my-first-extension-0.0.1.vsix のようなファイルが生成されます。このファイルを VS Code にドラッグ＆ドロップするか、拡張機能サイドバーのメニューから「VSIX からのインストール」を選択することで、手動で拡張機能をインストールできます。

注意点として、パッケージ化を行う前に、package.json 内の publisher（公開者名）フィールドの設定や、README.md の編集（デフォルトのテンプレートテキストの削除）を行っておく必要があります。これらが未設定だとビルド時にエラーや警告が発生します。

Marketplace への公開手順

世界中のユーザーが拡張機能をダウンロードできるようにするためには、VS Code Marketplace に公開する必要があります。公開の大まかな手順は以下の通りです。

Azure DevOps アカウントの作成

Marketplace の管理には Microsoft アカウントと Azure DevOps が使用されます。Azure DevOps にログインして組織（Organization）を作成します。
パーソナルアクセストークン (PAT) の取得

Azure DevOps のユーザー設定から、Marketplace へのアクセス権限（Scopes: Marketplace (Publish)）を持った PAT を生成します。このトークンは後で認証に使用するため、厳重に保管してください。
公開プロファイルの登録とログイン

以下のコマンドを実行し、Marketplace に公開者（Publisher）を登録して、取得した PAT を使ってログインします。
```
vsce login <publisher-name>
```
拡張機能の公開

ログインが成功したら、以下のコマンドを実行して Marketplace に公開します。
```
vsce publish
```

これで、数分後に VS Code の拡張機能検索から、公開した拡張機能を検索してインストールできるようになります。

6. まとめと参考リソース

ガイドのまとめ

本ガイドでは、VS Code 拡張機能開発の基本的な手順について学びました。

前提環境の準備: Node.js, npm, Git, VS Code の用意
雛形の生成: yo code を使用した TypeScript プロジェクトの自動作成
実装とデバッグ: F5 キーでのデバッグ起動と、基本的な API の使い方
構成の理解: activationEvents と contributes の宣言的な定義
パッケージ化と公開: vsce を使用した .vsix ファイルの作成と Marketplace への登録

VS Code は非常にオープンなプラットフォームであり、一度基本を身につければ、自分好みの開発環境をいくらでもカスタマイズできます。

公式ドキュメントと参考リソース

さらに高度な拡張機能（言語サーバー、自動補完、デバッガ連携など）を開発するためには、以下の公式リソースを参照するのが最も確実です。

VS Code Extension API Documentation

拡張機能開発の公式ドキュメント（英語）です。API の詳細やチュートリアルが豊富に掲載されています。 URL: https://code.visualstudio.com/api
VS Code Extension Samples

Microsoft が GitHub で公開している、動くサンプルコード集です。Webview の使い方や言語サポートの追加方法など、具体的な実装例が数百種類あります。 URL: https://github.com/microsoft/vscode-extension-samples
VS Code API Reference

利用可能なクラスや関数の完全なリファレンスです。 URL: https://code.visualstudio.com/api/references/vscode-api

これらのドキュメントを活用し、まずは小さな拡張機能から作成してみてください。

Keyboard shortcuts