Erweiterungsstruktur

Im letzten Thema konnten Sie eine grundlegende Erweiterung zum Laufen bringen. Wie funktioniert sie im Hintergrund?

Die Hello World-Erweiterung tut 3 Dinge

• Registriert das onCommand- Aktivierungsereignis: onCommand:helloworld.helloWorld, sodass die Erweiterung aktiviert wird, wenn der Benutzer den Hello World-Befehl ausführt.

  Hinweis: Ab VS Code 1.74.0 aktivieren Befehle, die im Abschnitt commands von package.json deklariert sind, die Erweiterung automatisch, wenn sie aufgerufen werden, ohne dass ein expliziter onCommand-Eintrag in activationEvents erforderlich ist.

• Verwendet den contributes.commands Contribution Point, um den Befehl Hello World in der Befehlspalette verfügbar zu machen und ihn an eine Befehls-ID helloworld.helloWorld zu binden.
• Verwendet die commands.registerCommand VS Code API, um eine Funktion an die registrierte Befehls-ID helloworld.helloWorld zu binden.

Das Verständnis dieser drei Konzepte ist entscheidend für das Schreiben von Erweiterungen in VS Code

• Aktivierungsereignisse: Ereignisse, bei denen Ihre Erweiterung aktiv wird.
• Contribution Points: Statische Deklarationen, die Sie in der package.json Extension Manifest vornehmen, um VS Code zu erweitern.
• VS Code API: Eine Reihe von JavaScript-APIs, die Sie in Ihrem Erweiterungscode aufrufen können.

Im Allgemeinen würde Ihre Erweiterung eine Kombination aus Contribution Points und der VS Code API verwenden, um die Funktionalität von VS Code zu erweitern. Das Thema Übersicht über Erweiterungsfunktionen hilft Ihnen, den richtigen Contribution Point und die richtige VS Code API für Ihre Erweiterung zu finden.

Schauen wir uns den Quellcode des Hello World-Beispiels genauer an und sehen, wie diese Konzepte darauf angewendet werden.

Dateistruktur der Erweiterung

.
├── .vscode
│   ├── launch.json     // Config for launching and debugging the extension
│   └── tasks.json      // Config for build task that compiles TypeScript
├── .gitignore          // Ignore build output and node_modules
├── README.md           // Readable description of your extension's functionality
├── src
│   └── extension.ts    // Extension source code
├── package.json        // Extension manifest
├── tsconfig.json       // TypeScript configuration

Sie können mehr über die Konfigurationsdateien lesen

• launch.json zur Konfiguration des VS Code Debuggens
• tasks.json für die Definition von VS Code Tasks
• tsconfig.json konsultieren Sie das TypeScript Handbuch

Konzentrieren wir uns jedoch auf package.json und extension.ts, die für das Verständnis der Hello World-Erweiterung unerlässlich sind.

Erweiterungsmanifest

Jede VS Code-Erweiterung muss eine package.json als ihr Extension Manifest haben. Die package.json enthält eine Mischung aus Node.js-Feldern wie scripts und devDependencies sowie VS Code-spezifischen Feldern wie publisher, activationEvents und contributes. Beschreibungen aller VS Code-spezifischen Felder finden Sie in der Referenz zum Erweiterungsmanifest. Hier sind einige der wichtigsten Felder

• name und publisher: VS Code verwendet <publisher>.<name> als eindeutige ID für die Erweiterung. Zum Beispiel hat das Hello World-Sample die ID vscode-samples.helloworld-sample. VS Code verwendet die ID, um Ihre Erweiterung eindeutig zu identifizieren.
• main: Der Einstiegspunkt der Erweiterung.
• activationEvents und contributes: Aktivierungsereignisse und Contribution Points.
• engines.vscode: Dies gibt die Mindestversion der VS Code API an, von der die Erweiterung abhängt.

{
  "name": "helloworld-sample",
  "displayName": "helloworld-sample",
  "description": "HelloWorld example for VS Code",
  "version": "0.0.1",
  "publisher": "vscode-samples",
  "repository": "https://github.com/microsoft/vscode-extension-samples/helloworld-sample",
  "engines": {
    "vscode": "^1.51.0"
  },
  "categories": ["Other"],
  "activationEvents": [],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "helloworld.helloWorld",
        "title": "Hello World"
      }
    ]
  },
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./"
  },
  "devDependencies": {
    "@types/node": "^8.10.25",
    "@types/vscode": "^1.51.0",
    "tslint": "^5.16.0",
    "typescript": "^3.4.5"
  }
}

Hinweis: Wenn Ihre Erweiterung auf eine VS Code-Version vor 1.74 abzielt, müssen Sie onCommand:helloworld.helloWorld explizit in activationEvents auflisten.

Einstiegsdatei der Erweiterung

Die Einstiegsdatei der Erweiterung exportiert zwei Funktionen: activate und deactivate. activate wird ausgeführt, wenn Ihr registriertes Aktivierungsereignis eintritt. deactivate gibt Ihnen die Möglichkeit, aufzuräumen, bevor Ihre Erweiterung deaktiviert wird. Für viele Erweiterungen ist möglicherweise kein explizites Aufräumen erforderlich, und die Methode deactivate kann entfernt werden. Wenn eine Erweiterung jedoch eine Operation ausführen muss, wenn VS Code heruntergefahren wird oder die Erweiterung deaktiviert oder deinstalliert wird, ist dies die Methode dafür.

Die VS Code-Erweiterungs-API wird in den @types/vscode-Typdefinitionen deklariert. Die Version der vscode-Typdefinitionen wird durch den Wert im Feld engines.vscode in package.json gesteuert. Die vscode-Typen bieten Ihnen IntelliSense, Go to Definition und andere TypeScript-Sprachfunktionen in Ihrem Code.

// The module 'vscode' contains the VS Code extensibility API
// Import the module and reference it with the alias vscode in your code below
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('Congratulations, your extension "helloworld-sample" 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
  let disposable = vscode.commands.registerCommand('helloworld.helloWorld', () => {
    // 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);
}

// this method is called when your extension is deactivated
export function deactivate() {}