Example －Hello World

Your First Extension

この文書は、あなたが、あなたの最初のVS Code拡張（「Hello World」）を作成することを通して、取得し、そして、基本的なVS Codeの拡張の概念を説明します。

このチュートリアルで、あなたは、VS Codeに、簡単な「Hello World」メッセージを表示する新しいコマンドを追加します。チュートリアルの後半に、 あなたは、ユーザーの現在選択したテキストのために、VS Codeのエディタと問合せと対話するでしょう。

Prerequisites

あなたは、あなたの$PATHに、インストールされ、そして、利用できるnode.jsが必要です。

Generate a New Extension

VS Codeに、あなた独自の機能を追加する最も簡単な方法は、コマンドを追加することです。 コマンドは、Command Paletteから、あるいは、キー・バインディングで呼び出すことができるコールバック関数を登録します。

私たちは、あなたが開始することを助ける、Yeomanジェネレーターを記述しました。 YeomanとYeoman VS Code拡張ジェネレーターをインストールして、新しい拡張の足場を組みます。：

npm install -g yo generator-code
yo code

hello world拡張のため、あなたは、TypeScriptやJavaScriptの拡張のどちらかを作成することができます。 この使用例のため、私たちは、TypeScript拡張を選択します。

Running your Extension

• VS Codeを起動します。File > Open Folderを選択し、そして、あなたが作成したフォルダを選択します。
• F5を押す、あるいは、Debugアイコンをクリックし、そして、Startをクリックします。
• VS Codeの新しいインスタンスは、特別なモード（拡張開発ホスト）で開始するでしょう。そして、この新しいインスタンスは、現在、あなたの拡張を認識しています。
• F1を押して、Hello Worldと名前を付けたコマンドを実行します。
• おめでとうございます。あなたは、今、あなたの、はじめのVS Codeのコマンドを作成し、実行しました！

The Structure of an Extension

実行した後に、作成された拡張は、以下の構造を持っている必要があります。：

.
├── .gitignore
├── .vscode                     // VS Code integration
│   ├── launch.json
│   ├── settings.json
│   └── tasks.json
├── .vscodeignore
├── README.md
├── src                         // sources
│   └── extension.ts            // extension.js, in case of JavaScript extension
├── test                        // tests folder
│   ├── extension.test.ts      // extension.test.js, in case of JavaScript extension
│   └── index.ts                // index.js, in case of JavaScript extension
├── node_modules
│   ├── vscode                  // language services
│   └── typescript              // compiler for typescript (TypeScript only)
├── out                         // compilation output (TypeScript only)
│   ├── src
│   |   ├── extension.js
│   |   └── extension.js.map
│   └── test
│       ├── extension.test.js
│       ├── extension.test.js.map
│       ├── index.js
│       └── index.js.map
├── package.json                // extension's manifest
├── tsconfig.json               // jsconfig.json, in case of JavaScript extension
├── typings                     // type definition files
│   ├── node.d.ts               // link to Node.js APIs
│   └── vscode-typings.d.ts     // link to VS Code APIs
└── vsc-extension-quickstart.md // extension development quick start

これらのファイルの目的を通過して行き、そして、それらが、何を行うかについて説明します。：

The extension manifest: package.json

• package.json拡張マニフェスト（原文）の参考文献を読み込みください。
• package.json貢献の核心（原文）に関するより多くの情報
• 各々のVS Code拡張は、それとその機能を説明するpackage.jsonファイルを持っている必要があります。
• VS Codeは、起動時に、このファイルを読み込み、そして、すぐに、項目の各々の寄与に反応します。

TypeScript拡張マニフェストの例

{
    "name": "myFirstExtension",
    "description": "",
    "version": "0.0.1",
    "publisher": "",
    "engines": {
        "vscode": "^0.10.1"
    },
    "categories": [
        "Other"
    ],
    "activationEvents": [
        "onCommand:extension.sayHello"
    ],
    "main": "./out/src/extension",
    "contributes": {
        "commands": [{
            "command": "extension.sayHello",
            "title": "Hello World"
        }]
    },
    "scripts": {
        "vscode:prepublish": "node ./node_modules/vscode/bin/compile",
        "compile": "node ./node_modules/vscode/bin/compile -watch -p ./"
    },
    "devDependencies": {
        "typescript": "^1.6.2",
        "vscode": "0.10.x"
    }
}

備考

JavaScriptの拡張は、コンパイルが必要なく、スクリプトの領域を必要としません。

• この特定のpackage.jsonは、以下の拡張子を説明します。
• ラベル「Hello world」でエントリをCommand Palette（F1）に投稿します。 それは、「extension.sayHello」コマンドを呼び出します。
• 「extension.sayHello」コマンドが呼び出されるとき、（activationEventsが)読み込まれることを要求します。
• ファイル内に持つ、その中心となるJavaScriptコードは、「./out/src/extension.js」を呼び出します。

備考

VS Codeは、起動時に拡張コードをしきりに読み込みません。拡張は、記述する必要があります。 どんな状態の元で、activationEventsプロパティを通して、それは、アクティブ化（読み込む）する必要があります。

Code

作成された拡張コードは、extension.ts（あるいは、JavaScript拡張の場合、extension.js）です：

// The module 'vscode' contains the VS Code extensibility API
// Import the module and reference it with the alias vscode in your code below
// モジュールvscodeには、VS Codeの拡張APIが含まれています。
// モジュールをインポートし、以下のあなたのコードで、別名のvscodeで、それを参照します。

import * as vscode from 'vscode';

// this method is called when your extension is activated
// your extension is activated the very first time the command is executed
// あなたの拡張がアクティブ化されるとき、このメソッドは、呼び出されます。
// あなたの拡張は、コマンドが実行されると極めて迅速に、アクティブ化されます。

export function activate(context: vscode.ExtensionContext) {

    // Use the console to output diagnostic information (console.log) and errors (console.error)
    // This line of code will only be executed once when your extension is activated
//診断情報（console.log）とエラー（console.error）を出力するために、コンソールを使用します。
// あなたの拡張が、アクティブになると、この命令行だけが実行されます。

    console.log('Congratulations, your extension "my-first-extension" is now active!');

    // The command has been defined in the package.json file
    // Now provide the implementation of the command with  registerCommand
    // The commandId parameter must match the command field in package.json
// コマンドは、package.jsonファイルで定義されています。
//現在、registerCommandで、コマンドの実装を提供します。
// コマンドIDパラメータは、package.jsonで、コマンド領域と一致する必要があります。

    var disposable = vscode.commands.registerCommand('extension.sayHello', () => {
        // The code you place here will be executed every time your command is executed
// あなたのコマンドが実行されるたび、あなたが、ここに配置するコードが、実行されます


        // Display a message box to the user
// ユーザーにメッセージボックスを表示します

        vscode.window.showInformationMessage('Hello World!');
    });
    
    context.subscriptions.push(disposable);
}

• それぞれの拡張は、activate()という名前のそのメインファイル関数をエクスポートする必要があります。 package.jsonファイル内で、説明されるactivationEventsが、発生するとき、それをVS Codeは、一度だけ呼び出します。
• 拡張が、（spawnsプロセスのような）OSのリソースを使用する場合、拡張は、deactivate()という名前のそのメイン・ファイルから、 関数をエクスポートすることができます。その場所で、クリーンアップ作業を行うことができ、そして、VS Codeは、シャットダウン時に、その関数を呼び出します。
• この特定の拡張は、vscode APIをインポートし、続いて、コマンドを登録し、コマンド「extension.sayHello」が呼び出されるとき、 関連する機能が呼び出されます。コマンドの実装は、VS Codeで「Hello world」メッセージを表示します。

備考

package.jsonの項目は、Command Paletteにエントリを追加することに、関与します。 extension.ts/.jsのコードは、「extension.sayHello」の実装を定義します。

備考

TypeScript拡張のために、作成されたファイルout/src/extension.jsは、実行時に読み込まれ、VS Codeで実行されます。

Running your Extension

今、拡張に含まれるファイルの役割を明らかにします。ここに、あなたの拡張が、どのようにアクティブ化にされるかがあります。：

• 拡張開発インスタンスは、拡張を発見し、そのpackage.jsonファイルを読み込みます。
• 後で、F1を押したとき：
• 登録されたコマンドは、Command Paletteで表示されます。
• 現在、このリストの中に、package.json内で定義されるエントリ「Hello world」があります。
• 「Hello world」コマンドを選択するとき：
• 「extension.sayHello」コマンドが呼び出されます：
  • アクティブ化されたイベント「onCommand：extension.sayHello」が、作成されます。
  • それらのactivationEvents内の、このアクティブ化イベントのすべての一覧にされている拡張は、アクティブ化されます。
    • /out/src/extension.jsのファイルは、JavaScript VMで読み込まれます。
    • VS Codeは、エクスポートされたアクティベートしている関数を探して、それを呼び出します。
    • コマンド「extension.sayHello」は、登録され、そして、その実装は、現在、定義されます。
• コマンド「extension.sayHello」で実装された関数が、呼び出されます。
• コマンドの実装は、「Hello World」メッセージを表示します。

Debugging your Extension

単純に、ブレークポイントを設定します。たとえば、登録されたコマンドの内側、そして、拡張開発VS Codeインスタンス内の、「Hello world」コマンドを実行します。

備考

TypeScript拡張のために、それにもかかわらず、VS Codeは、読み込まれ、そして、out/src/extension.jsを実行します。 あなたは、実際に、作成されたソースマップout/src/extension.js.mapのために、元のTypeScriptコードをデバッグすることができます。 そして、VS Codeデバッガは、ソースマップをサポートしています。

ヒント：

Debug Consoleは、あなたが、コンソールに記録する、すべてのメッセージを表示するでしょう。

詳細については、拡張開発環境（原文）をご覧ください。

A Simple Change

extension.ts（あるいは、JavaScript拡張内のextension.js）では、エディタで選択された文字の数を表示するために、 extension.sayHelloコマンドの実装を置き換えてみます。：

var editor = vscode.window.activeTextEditor;
if (!editor) {
    return; // No open text editorテキストエディターを開いては行けません
}

var selection = editor.selection;
var text = editor.document.getText(selection);

// Display a message box to the user　ユーザーに、メッセージボックスを表示します
vscode.window.showInformationMessage('Selected characters: ' + text.length);

ヒント：

一旦、あなたが、拡張のソース・コードを変更すると、あなたは、VS Codeの拡張開発インスタンスを再開する必要があります。

あなたは、２つ目のインスタンスの中で、Ctrl+R (Mac: Cmd+R)を使用して、 あるいは、あなたの1つ目のVS Codeのインスタンスの一番上のRestartボタンをクリックすることによって、行うことができます。

Publishing your Extension

どのように、拡張を共有する（原文）かについて読んでください。

Next Steps

このチュートリアルで、私たちは、極めて簡単な拡張を見てきました。より詳細な例については、 ワード・カウントの例を参照してください。それは、特定の言語（Markdown）を対象とする方法を示します。そして、エディタの文書変更イベントを聞き取ります。

あなたが、拡張APIの全般的な詳細について知りたい場合、これらの項目に挑戦してください：

• 拡張APIの概要－完全なVS Codeの拡張性モデルについては、こちらをご覧ください。
• APIパターンと原則－VS Codeの拡張性は、いくつかの案内しているパターンと原則に基づいています。
• 貢献ポイント－さまざまなVS Codeの貢献についての詳細な情報については、こちらをご覧ください。
• アクティブ化イベント－VS Codeのアクティブ化イベントの参考文献

Common Questions

まだ、何もありません。