最新のVS Code拡張機能開発チュートリアル：安全な拡張機能を構築する

Microsoft Visual Studio（VS）Codeが広く成功を収め、大きな影響力を持つようになったのは、その拡張性によるところが大きいでしょう。コードエディターとして分類されることが多いものの、適切な知識と拡張機能があれば、それ以上の用途に活用できます。たとえば、ウェブブラウザー、ワープロ、ファイル管理システムとしても使えます。Microsoftは、VS Code APIをできる限り使いやすくすることで、開発者がVS Codeの拡張性を活用できるよう後押ししています。

VS Codeの拡張機能開発は、2016年のツール公開以来、大きく進化してきました。より効率的で、開発者にとって使いやすくなっています。それでも、独自の拡張機能を作り始める前に知っておくべき注意点や手法があります。

最新のVS Code拡張機能開発に関する最初のブログ記事では、アーキテクチャや作成できるさまざまな種類など、VS Code開発の基本を解説しました。この記事では、その知識を活用し、独自のVS Code拡張機能を作成してコードを書く方法をご紹介します。

VS Code拡張機能を構築する

このチュートリアルでは、複数の機能を備えたVS Code拡張機能を構築しながら、さまざまな種類の拡張機能を実装する方法を学びます。完成したプロジェクトはこちらのGitHubリポジトリで確認できます。

VS Code拡張機能プロジェクトのひな形を作成する

このチュートリアルを進めるには、いくつか準備が必要です。VS Code、VS Codium、またはVS Code Insidersに加えて、次のツールがインストールされていることを確認してください。

• Node.js

• Git

これらを使ってYeomanとVS Code Extension Generatorをインストールします。このジェネレーターは拡張機能のひな形（スキャフォールド）を作成するため、すべてをゼロから書く必要はありません。このブログではTypeScriptの使用を推奨します。TypeScriptでプロジェクトを作成する場合は、コードのエラーを見つけて紐付けやすくするため、TypeScript + Webpack Problem Matcherもインストールすることをおすすめします。

Node.jsとGitをインストールしたら、任意のシステムコマンドラインインタープリター（コマンドプロンプト、PowerShell、ターミナルなど）を開き、次のコマンドを実行します。

npm install -g yo generator-code

YeomanとそのVS Code Extension Generatorのインストールには、少し時間がかかります。

インストールが完了したら、ターミナルでプロジェクトフォルダー（プロジェクトを保存する場所）に移動し、次のコマンドを実行します。

yo code

Yeoman CLIが起動し、ひな形を作成するプロジェクトの種類を選択するよう求められます。New Extension (TypeScript)を選択することをおすすめします。ただし、JavaScriptのほうが使い慣れている場合は、2番目の選択肢を選んでください。

次にジェネレーターから、拡張機能の名前を入力するよう求められます。「My Editor Tools」のようなシンプルな名前を付けましょう。さらに、editor-toolsのような拡張機能の識別子も入力します。

拡張機能の説明には、次の文を使ってください。「VS Code向けのシンプルな編集ツール集。」続いて、プロジェクト用のGitリポジトリを初期化するかどうかを選びます。初期化は後で手動で行うこともできます。

この時点で、ソースコードをwebpackでバンドルするかどうかを尋ねられます。バンドルすることを確認し、パッケージマネージャーとしてnpmを選択してください。

ジェネレーターによるプロジェクトのひな形作成には、少し時間がかかります。完了すると、システムで利用できるVS Codeのエディションでプロジェクトを開くかどうかを尋ねられます。Enterを押して開きます。プロジェクトのソースコードが、新しいVS Codeウィンドウに表示されます。

注意：このチュートリアルでは、Visual Studio Code 1.79、npm 9.5.1、Yeoman 4.3.1を使用しています。そのため、使用するバージョンによってはプロジェクトの初期化手順が多少異なる場合があります。必要に応じて手順を調整してください。CLIではなくグラフィカルなセットアップを使いたい場合は、今後のプロジェクトに備えてYeoman Application Wizardをインストールしてください。

プロジェクトを準備する

Yeomanのバージョンによっては、package.jsonファイルでvscodeモジュールを参照する形でプロジェクトのひな形が作成されている場合があります。このモジュールは今でも広く使われていますが、セキュリティ上の理由から非推奨となっています。該当する場合は、必ずプロジェクトを更新してください。

プロジェクトの準備として、まず@types/vscodeパッケージがインストールされ、プロジェクトの開発用依存関係として宣言されていることを確認します。VS Code Explorerでプロジェクトのpackage.jsonファイルを開き、すべての依存関係を確認してください。

package.jsonファイルを開いたら、"devDependencies"オブジェクトが見つかるまで下にスクロールします。その中に"@types/vscode": [version],というキーと値が定義されていることを確認してください。

さらに、@types/vscodeパッケージのバージョン番号がVS Codeのエンジンバージョンと一致していることを確認します。そのために、package.jsonファイルを上にスクロールして"engines"オブジェクトを探します。VS Codeのエンジンバージョン番号は"vscode"キーの横にあります。

@types/vscodeのバージョン番号がエンジンバージョンと一致しない場合は、@type/vscodeのバージョン番号を手動で変更して合わせてください。

@types/vscodeパッケージがpackage.json`ファイルにまったく見つからない場合は、自分でダウンロードして追加しないでください。コマンドラインターミナルを起動し、プロジェクトのルートフォルダー（cd editor-tools）に移動してから、npmで必要なパッケージをインストール・設定してください。次のコマンドを入力して実行します。

npm install --save-dev @types/vscode

package.jsonを再度確認し、必要なモジュールがすべて参照されていることを確かめます。プロジェクトで適切なvscodeモジュールを使っているか確認するのは、拡張機能の作成に最も安全なライブラリを使用するためです。これにより、カスタム拡張機能の安全性を確保できます。

古いVS Code npmパッケージを更新して2つのパッケージに分割する判断には、さまざまな要因がありました。主な理由の1つは、元のパッケージにevent-streamという侵害されたパッケージへの間接的な依存関係が含まれていたことです。この変更は、パフォーマンスの向上、複雑さの軽減、新機能の導入に加えて、VS Codeモジュールのセキュリティを強化することを目的としています。  

 ただし、プロジェクトのセキュリティと品質について、事前チェックも実施することをおすすめします。これにより、プロジェクトが正しく安全にひな形作成されていることを確認できます。

プロジェクトを検証する

プロジェクトのインストールが安全かどうかを確認するには、Snykを利用できます。VS CodeのワークフローにSnykのツールを導入する最も簡単な方法は、Snykの無料アカウントに登録してからSnyk拡張機能をインストールすることです。

Snyk拡張機能をインストールしたら、Extensionsウィンドウを開いて「Snyk」を検索します。検索結果の最初に表示されるはずのrelease版をインストールしてください。

または、ウェブ版のVisual Studio Code Marketplaceから公式Snyk拡張機能を追加できます。

インストールが完了したら、認証を行い、VS Code拡張機能をSnykアカウントに接続します。プライマリーサイドバーにあるSnykバッジをクリックし、Trust workspace and connectをクリックしてください。

既定のウェブブラウザーでSnyk認証ページが開きます。大きな緑色のAuthenticateボタンをクリックしてください。認証に成功すると、アカウントが認証され、Snykを利用できる状態になったことを示すメッセージが表示されます。

拡張機能を適切に設定するため、公式のSnyk VS Code Extension Configurationドキュメントを読むことをおすすめします。変更を加えたら、VS Codeを再読み込みまたは再起動するのが最善です。その後、VS CodeでSnyk拡張機能のUIに戻り、Enable Snyk Code and Start Scanningボタンをクリックします（ボタンが表示されない場合は、次の注意をご覧ください）。  

注意：ボタンが表示されない場合、Snykはプロジェクトのスキャンを自動的に開始するはずです。また、プロジェクトフォルダーを信頼するかどうか、VS Codeから確認される場合があります。これは正常な動作です。確認画面が表示されたら、Trust Folder and Continueボタンをクリックしてください。

Snyk拡張機能の既定の設定を使用している場合、SnykはOpen Source SecurityとConfigurationのスキャンを自動的に実行します。SnykパネルのCode Security and Qualityセクションに、Enable Snyk Code and start analysingというボタンが表示されます。VS CodeにEnable Snyk Codeボタンが表示される場合もあります。

どちらかのボタンをクリックすると、Snyk Code Settingsページが開きます。そこでは、Snyk Codeの概要を確認できます。内容を読んだら、Save changesをクリックしてください。 

VS CodeのUIとSnykパネルに戻ります。しばらくすると、SnykパネルにCode SecurityとCode Qualityのセクションが表示され、スキャンが開始されます。 

拡張機能のUIパネルは、次の4つの部分で構成されています。

1. オープンソースのセキュリティ

2. コードセキュリティ

3. 構成

4. コード品質

Code SecurityとCode Qualityの機能でスキャンが自動的に開始されない場合は、それぞれのタイトル横にあるPlayボタンをクリックしてください。Playボタンはセクションにカーソルを合わせると表示され、プロジェクトを再スキャンできます。

最初のスキャン後、Open Source Security and Configurationスキャナーでは問題が検出されないはずです（脆弱性や問題が見つからない状態）。一方、Code SecurityとCode Qualityでは、いくつかの問題や脆弱性が表示されます。

詳しく確認するには、分析結果を展開してください。ほとんどの問題は依存関係で見つかったもので、重要度は低いものです。これらのファイルを変更することもできますが、スキップするのが望ましいでしょう。

Analysis Resultsパネルでアラートを確認し、必要に応じて無視したり例外を設定したりします（外部プロジェクトモジュールなど）。プロジェクトの準備ができたら、拡張機能を実行して動作を確認しましょう。

拡張機能を実行する

拡張機能を実行するには、VS Code ExplorerでEditor-Tools/src/extension.tsファイルに移動します。C#やJavaなどのプログラミング言語におけるオブジェクト指向設計パターンに慣れている方なら、これはmainクラスと同様の役割を果たします。

extension.tsファイルには、Yeoman VS Code拡張機能コードジェネレーターが生成したサンプルコードが含まれているはずです。F5キーを押して、このコードと前のセクションで加えた変更をテストします。

注意：VS Codeからビルドタスクの指定を求められる場合があります。これは通常、tasks.jsonファイルに既定のタスクが設定されていない場合に発生します。その場合は、ビルドタスクとしてnpm: compileを選択してください。

VS CodeがExtension Development Hostを起動する前に、起動前タスクnpm: watchの実行後にエラーが見つかったことを知らせるダイアログが表示される場合があります。これはまったく問題ありません。Remember my choice in user settingsチェックボックスをオンにしてから、Debug Anywayボタンをクリックしてください。

Extension Development Hostが起動したら、Ctrl + Shift + P（Windows）またはShift + Command + P（Mac）を押して、Command Paletteを開きます。続いて、Command PaletteのテキストフィールドにHello Worldコマンドを入力します。右下隅に小さなポップアップメッセージが表示されます。

拡張機能の実行／デバッグセッションを終了するには、Development Hostを必ず閉じてください。次のセクションでは、いよいよ拡張機能を構築します。

拡張機能を構築して変更する

このセクションでは、VS Codeのアクティブなテキストエディターにテキストを追加する簡単な機能を作成します。仕組みとしては、Excelなどのアプリケーションにあるオートフィル機能と似ています。

まず、VS Codeのエクスプローラーをクリックし、プロジェクトのソースコードディレクトリ（SRC）にAutoFillExtension.tsという新しいファイルを追加します。

次のコードをAutoFillExtension.tsファイルに追加します。

1import * as vscode from 'vscode';
2
3export function autofillMyAddress() {
4    //Retrieve the currently active text editor
5    const editor = vscode.window.activeTextEditor;
6    //Check if the editor is undefined
7    if (editor) {
8        //Insert text at the current position using an edit builder
9        editor.edit(editBuilder => {
10            editBuilder.insert(editor.selection.active,'Street 6260-112 Glenwood Ave'
11            +'\nCity/Town   Raleigh'
12            +'\nState/Province/Region   Nebraska'
13            +'\nZip/Postal Code 27612'
14            +'\nPhone Number    (919) 785-2864'
15            +'\nCountry United States'
16            +'\nLatitude    35.859171'
17            +'\nLongitude   -78.703853');
18        });
19    }
20}

このコードでは、autoFillMyAddressという関数を宣言してエクスポートします。この関数は、VS Code APIのwindow namespaceを使って、現在アクティブなテキストエディター（現在のウィンドウにフォーカスがあるエディターパネル）を取得します。アクティブなエディターがあることを確認してから、TextEditorEditクラスのインスタンスを使ってテキスト（ランダムに生成された架空の住所）を追加します。

拡張機能を作成したら、登録して呼び出す必要があります。そのために、VS Codeのエクスプローラーでpackage.jsonファイルを開きます。拡張機能の機能をVS CodeのUIからコマンドとして呼び出せるように、コントリビューションポイントを追加します。

package.jsonファイルをゆっくり下にスクロールし、"contributes"オブジェクトを見つけます。"command"配列とその値を、次のコードに置き換えます。

"commands": [
    {
        "command": "editor-tools.fillAddress",
        "title": "Fill Address"
    }
]

プロジェクトのextension.tsファイルに戻り、内容を次のように置き換えます。

1// The module 'vscode' contains the VS Code extensibility API
2// Import the module and reference it with the alias vscode in your code below
3import * as vscode from 'vscode';
4import * as autofill from './AutoFillExtension';
5
6// This method is called when your extension is activated
7// Your extension is activated the very first time the command is executed
8export function activate(context: vscode.ExtensionContext) {
9    let disposable = vscode.commands.registerCommand('editor-tools.fillAddress',autofill.autofillMyAddress);
10
11    context.subscriptions.push(disposable);
12}
13
14// This method is called when your extension is deactivated
15export function deactivate() {}

このコードでは、AutoFillExtensionモジュールをautofillオブジェクトとしてインポートします。次にactivateを使って拡張機能のコマンドを登録し、拡張機能をExtensionContextのサブスクリプションリストに追加します。拡張機能が無効化されると、VS Codeによって破棄されます。

ここで、拡張機能をデバッグ／実行します（F5）。拡張機能を使うには、編集可能な新しいファイル（種類は問いません）を開くか作成します。次にコマンドパレットを開き、Fill Addressコマンドを入力します。

次は、VS Codeの診断機能を活用して、拡張機能をさらに強化しましょう。この機能を追加すると、現在のドキュメントが特定の条件を満たしているかどうかを確認できます。条件を満たしていない場合は、拡張機能がエラーメッセージを表示します。

Extension Development Hostを閉じ、srcフォルダーにLineDiagnosticExtension.tsという新しい拡張機能を作成して、次の内容を追加します。

1import * as vscode from 'vscode';
2
3export function updateDiagnostic(collection: vscode.DiagnosticCollection) {
4    //clears previous errors
5    collection.clear;
6    //fetches current active text editor
7    let editor = vscode.window.activeTextEditor;
8    //ensures that active text editor is not undefined
9    if (editor) {
10        //fetches the document from the active text editor
11        let document = editor.document;
12        //fetches the number of lines
13        let lineCount = document.lineCount;
14        //verifies that the line count is not less than 8
15        if (lineCount < 8) {
16            //specifies the range to highlight and display errors over
17            const diagnosticrange = new vscode.Range(new vscode.Position(0, 0), new vscode.Position(lineCount-1, 10));
18            //sets the properties of VSCode's diagnostic features
19            collection.set(document.uri, [{
20                code: '',
21                message: 'Document has only ' + lineCount + ' line(s). The document must have at least 8 lines',
22                range: diagnosticrange,
23                severity: vscode.DiagnosticSeverity.Error,
24                source: '',
25                relatedInformation: [
26                    new vscode.DiagnosticRelatedInformation(new vscode.Location(document.uri, new vscode.Range(new vscode.Position(0, 0), new vscode.Position(7, 10))), 'Line Count')
27                ]
28            }]);
29        } else {
30            //if the line count is equal to or greater than 8, it clears all error messages
31            collection.clear();
32
33        }
34
35    }  
36
37}    

このファイルには、updateDiagnostic()という関数だけが含まれており、エクスポートされます。引数はDiagnosticCollectionの1つです。この関数はTextDocumentモジュールのlineCountプロパティを使って、現在アクティブなドキュメントの行数を取得します。行数が8行未満の場合は、VS Codeの診断機能を使ってエラーメッセージを表示します。診断機能には、画面上に浮かぶポップアップウィンドウと、問題パネルへの表示が含まれます。

次に、UpdateDiagnostic()を呼び出し、拡張機能の一部として登録します。extension.tsファイルを開き、内容を次のように置き換えます。

1// The module 'vscode' contains the VS Code extensibility API
2// Import the module and reference it with the alias vscode in your code below
3import * as vscode from 'vscode';
4import * as autofill from './AutoFillExtension';
5import * as linelimit from './LineDiagnosticExtension';
6
7// This method is called when your extension is activated
8// Your extension is activated the very first time the command is executed
9export function activate(context: vscode.ExtensionContext) {
10    //create a new diagnostic collection
11    const collection = vscode.languages.createDiagnosticCollection('line count diagnostics');
12    vscode.commands.registerCommand('editor-tools.fillAddress',autofill.autofillMyAddress);
13
14    //Initial run of the upDateDiagnostic method
15    linelimit.updateDiagnostic(collection);
16
17    //Subscribes a new event handler that activates when an edit or change is performed on a workspace document  
18    context.subscriptions.push(vscode.workspace.onDidChangeTextDocument(editorchangeevent => {      
19        if (editorchangeevent) {
20            linelimit.updateDiagnostic(collection);
21        }
22    }));
23
24}
25
26// This method is called when your extension is deactivated
27export function deactivate() {}

このコードでは、LineDiagnosticExtension.tsをlinelimitというエイリアスでインポートします。次に、新しいDiagnosticCollectionを定義します。これはactivate関数が呼び出されたときに一度だけ実行されます。Fill Addressコマンドを登録した後、updateDiagnostic()関数を呼び出します。この関数もVS Codeの起動時に一度だけ実行されます。

VS Codeの診断情報を更新するには、ドキュメントの変更を監視する必要があります。そのため、このコードでは、ワークスペースに属し、現在のワークスペース内のすべてのドキュメント編集を監視するOnDidChangeTextDocument()というイベントハンドラーを登録します。

次に、イベントハンドラーがlinelimit.updateDiagnosticメソッドを実行します。2つの異なる拡張機能があるため、両方を登録する必要があります。前の例では、コマンドパレットからコマンドを実行したときにのみ、Fill Address拡張機能とコマンドが登録され、サブスクリプションリストに追加されます。一方、ここではVS Codeの初期化時に有効化されるようにします。

VS Codeでは、アクティベーションイベントを指定できます。拡張機能は、アクティベーションイベントが発生した場合にのみ有効化されます。

プロジェクトのpackage.jsonファイルを開きます。下にスクロールしてactivationEvents配列を見つけ、値として"*"を（角括弧の間に）追加します。これにより、すべてのアクティベーションイベントで、すべての拡張機能がVS Codeによって有効化されます。VS Codeの起動時間が長くなるため、通常は推奨されない方法です。ただし、ここで作成するのはシンプルな拡張機能なので、プロジェクトに影響はないはずです。

  "activationEvents": [
    "*"
  ],

いよいよ、拡張機能を実行してテストします。テストするには、新しいテキストファイルを作成し、テキスト領域に適当な内容を入力します。VS Codeでテキストに赤い下線が引かれ、問題パネルにメッセージが表示されるはずです。

さらに8行追加すると、エラーメッセージが消えます。簡単に済ませるには、Fill Addressメソッドを使います。

次に、Snykを再度実行して、プロジェクトの品質とセキュリティを確認します。スキャン結果を確認し、作成したプロジェクトファイルに関係のないアラートは無視してください。関連する通知が見つかった場合は、Snykの推奨に従って修正します。拡張機能とその依存関係の品質およびセキュリティを確認できたら、公開する準備は完了です。

拡張機能をパッケージ化する

Microsoftが提供するVS Code Extensions（VSCE）CLIを使えば、パッケージ化と公開を簡単に行えます。このツールを使うと、拡張機能を必ずしもVisual Studio Code Marketplaceに公開する必要はありません。VSIXファイルとしてパッケージ化し、その形で共有できます。VSCE CLIのインストールにはnpmが必要です。

任意のコマンドラインターミナルを開き、次のnpmコマンドを実行します（特定のディレクトリで実行する必要はありません）。

npm install -g @vscode/vsce

VSCEをインストールしたら、拡張機能のフォルダーに移動し、次のコマンドを実行します。

vsce package

拡張機能用のGitHubリポジトリを初期化しないことを選んだ場合、いくつかの警告が表示されることがあります。yesを選択すれば、これらの警告を回避できます。

パッケージ化にはそれほど時間はかかりません。完了すると、プロジェクトのルートフォルダーにeditor-tools-0.0.1.vsix（または類似の名前）の新しいファイルが作成されます。

このファイルを使って、お使いのVS Codeに拡張機能をインストールできます。VS Codeを開き、拡張機能パネルに移動します。上部にある三点リーダーのメニューアイコン（表示とその他の操作）をクリックし、VSIXからインストールを選択します。

ファイル選択画面が開きます。拡張機能を探して選択し、インストールボタンをクリックします。

インストールが完了すると、画面右下に通知ポップアップが表示されます。

これで、お使いのVS Codeから拡張機能の機能にアクセスできるようになります。

拡張機能を公開する

実際にVisual Studio Code Marketplaceで公開する拡張機能であれば、ここで公開作業を行います。今回はこのサンプル拡張機能を公開せず、手順を紹介するだけにします。

注意：Marketplaceにデモアプリケーションが大量に投稿されるのを避けるため、この手順を実際に行うことはおすすめしません。ただし、一般公開する拡張機能を開発する際に備えて、以下の手順を参考にしてください。

パッケージを公開するには、組織用のAzure DevOpsアカウントを作成し、それを使って個人用アクセストークンを取得します。

Visual Studio Code Marketplaceの発行元管理ページから、新しい発行元を作成できます。発行元名と発行元の表示名は、どちらも一意である必要があります。

新しい発行元を作成したら、package.jsonファイルに発行元のキーと値を追加します。表示名ではなく、発行元名を指定してください。

"publisher": "publisher name" //Publisher name and value

"name": "editor-tools",
"displayName": "My Editor Tools",
"description": "A collection of simple editing tools for VSCode",
"version": "0.0.1",

次に、発行元名（ID）と個人用アクセストークンを使ってVSCEにログインします。

vsce login <publisher ID>

ログインに成功したら、拡張機能プロジェクトのルートフォルダーで次のコマンドを実行して、VSCEから拡張機能を公開できます。

vsce publish

または、VSIXをVisual Studio Code Marketplaceの発行元管理ページに手動でアップロードすることもできます。ひな形の作成時に拡張機能をバンドルしなかった場合は、webpackまたはesbuildを使って手動でバンドルできます。バンドルすると、拡張機能の効率と読み込み時間を改善できます。

ここではバンドルは必須ではありませんが、今後のプロジェクトでは必要になる場合があります。バンドルする前に、プロジェクトが依存するすべての依存関係が安全であることを確認してください。Snykでプロジェクトをスキャンすれば、参照しているライブラリやモジュールがサイバーセキュリティ上安全かどうかをすばやく確認できます。

また、テクノロジーとサイバーセキュリティは常に変化しているため、今は安全な依存関係でも、将来も安全とは限りません。Snykを使えば、プロジェクトの依存関係を継続的に監視できます。潜在的な脆弱性が見つかった場合、SnykからメールまたはSlackで通知が届きます。

まとめ

このチュートリアルでは、VS Code用のシンプルな拡張機能を作成する方法を学びました。YeomanのVSCEジェネレーターを使ったプロジェクトの初期化から、拡張機能の基本的な構造、拡張機能マニフェスト（package.json）を使ったさまざまな種類の拡張機能の登録と有効化、拡張機能のパッケージ化、バンドル、公開までを解説しました。

VS Code拡張機能でも複雑なWebアプリでも、サイバーセキュリティを真剣に考える必要があります。しかし、継続的インテグレーションと継続的デリバリー（CI/CD）の導入が進む中、それは簡単ではありません。この課題に対処するため、Snykはコード品質とセキュリティのチェックを自動化し、最新の業界標準への準拠を支援します。Snykがこうした作業を担うため、サイバーセキュリティの動向やセキュアコーディングの実践に取り残される心配を軽減できます。