확장 프로그램 구조

이전 토픽에서는 기본적인 확장 기능을 실행할 수 있었습니다. 이 확장 기능은 내부적으로 어떻게 작동할까요?

Hello World 확장 기능은 세 가지 작업을 수행합니다.

onCommand 활성화 이벤트를 등록합니다: onCommand:helloworld.helloWorld. 이를 통해 사용자가 Hello World 명령을 실행할 때 확장 기능이 활성화됩니다.
참고: VS Code 1.74.0부터 package.json의 commands 섹션에 선언된 명령은 명시적인 onCommand 항목 없이도 호출될 때 확장 기능을 자동으로 활성화합니다.
contributes.commands 기여 포인트를 사용하여 명령 팔레트에서 Hello World 명령을 사용할 수 있게 하고, 이를 명령 ID helloworld.helloWorld에 바인딩합니다.
commands.registerCommand VS Code API를 사용하여 등록된 명령 ID helloworld.helloWorld에 함수를 바인딩합니다.

이 세 가지 개념을 이해하는 것은 VS Code에서 확장 기능을 작성하는 데 매우 중요합니다.

활성화 이벤트: 확장 기능이 활성화되는 이벤트입니다.
기여 포인트: VS Code를 확장하기 위해 package.json 확장 기능 매니페스트에 선언하는 정적 선언입니다.
VS Code API: 확장 기능 코드에서 호출할 수 있는 JavaScript API 세트입니다.

일반적으로 확장 기능은 기여 포인트와 VS Code API를 조합하여 VS Code의 기능을 확장합니다. 확장 기능 기능 개요 토픽은 확장 기능에 적합한 기여 포인트와 VS Code API를 찾는 데 도움이 됩니다.

Hello World 샘플의 소스 코드를 자세히 살펴보고 이러한 개념이 어떻게 적용되는지 알아보겠습니다.

확장 기능 파일 구조

.
├── .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

설정 파일에 대해 더 자세히 읽어볼 수 있습니다.

launch.json: VS Code 디버깅을 구성하는 데 사용됩니다.
tasks.json: VS Code 작업을 정의하는 데 사용됩니다.
tsconfig.json: TypeScript 핸드북을 참조합니다.

하지만 Hello World 확장 기능을 이해하는 데 필수적인 package.json과 extension.ts에 집중해 보겠습니다.

확장 프로그램 매니페스트

모든 VS Code 확장 기능에는 확장 기능 매니페스트로서 package.json 파일이 있어야 합니다. package.json은 scripts 및 devDependencies와 같은 Node.js 필드와 publisher, activationEvents, contributes와 같은 VS Code 특정 필드를 혼합하여 포함합니다. VS Code 특정 필드에 대한 모든 설명은 확장 기능 매니페스트 참조에서 찾을 수 있습니다. 다음은 가장 중요한 필드입니다.

name 및 publisher: VS Code는 <publisher>.<name>을 확장 기능의 고유 ID로 사용합니다. 예를 들어, Hello World 샘플의 ID는 vscode-samples.helloworld-sample입니다. VS Code는 이 ID를 사용하여 확장 기능을 고유하게 식별합니다.
main: 확장 기능의 진입점입니다.
activationEvents 및 contributes: 활성화 이벤트 및 기여 포인트입니다.
engines.vscode: 확장 기능이 의존하는 VS Code API의 최소 버전을 지정합니다.

{
  "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"
  }
}

참고: 확장 기능이 1.74 이전 버전의 VS Code를 대상으로 하는 경우 activationEvents에 onCommand:helloworld.helloWorld를 명시적으로 나열해야 합니다.

확장 기능 진입 파일

확장 기능 진입 파일은 activate와 deactivate 두 함수를 내보냅니다. activate는 등록된 활성화 이벤트가 발생할 때 실행됩니다. deactivate는 확장 기능이 비활성화되기 전에 정리할 기회를 제공합니다. 많은 확장 기능의 경우 명시적인 정리가 필요하지 않을 수 있으며 deactivate 메서드는 제거될 수 있습니다. 그러나 확장 기능이 VS Code 종료 시 또는 확장 기능이 비활성화되거나 제거될 때 작업을 수행해야 하는 경우 이 메서드를 사용합니다.

VS Code 확장 API는 @types/vscode 타입 정의에 선언되어 있습니다. vscode 타입 정의의 버전은 package.json의 engines.vscode 필드 값으로 제어됩니다. vscode 타입은 코드에서 IntelliSense, 정의로 이동 및 기타 TypeScript 언어 기능을 제공합니다.

// 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() {}

12/10/2025