Создание и публикация расширения для Visual Studio Code

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВНЕ ДЛЯ НОВИЧКОВВ РАЗРАБОТКЕ

Разработчику Архитектору Инженеру

Создание и публикация расширения для Visual Studio Code

Visual Studio Code — это не просто редактор кода, а полноценная платформа с открытым исходным кодом, поддерживающая расширения. Расширения позволяют адаптировать среду под любые задачи: добавлять поддержку новых языков, интегрировать внешние сервисы, автоматизировать рутинные действия или даже создавать собственные интерфейсы внутри редактора.

Эта глава посвящена полному циклу разработки расширения для VS Code: от понимания архитектуры и возможностей до создания, тестирования и публикации готового решения.

Что такое расширение для Visual Studio Code

Расширение для Visual Studio Code — это программный модуль, написанный на JavaScript/TypeScript с использованием Node.js и специального API, предоставляемого самой платформой VS Code. Расширение может взаимодействовать с редактором на разных уровнях: от простого добавления команд до изменения пользовательского интерфейса, анализа кода в реальном времени или запуска фоновых процессов.

Расширения работают в двух основных контекстах:

UI-контекст: элементы интерфейса, такие как панели, деревья, кнопки, уведомления.
Рабочий контекст: обработка файлов, выполнение команд, взаимодействие с системой, запуск скриптов.

Каждое расширение представляет собой папку с определённой структурой, содержащую метаданные (package.json), исходный код (обычно TypeScript), ресурсы (иконки, локализации) и конфигурационные файлы сборки.

Технологический стек расширений VS Code

Язык программирования

Основной язык разработки расширений — TypeScript. Он рекомендуется официальной документацией Microsoft и используется во всех шаблонах генератора yo code. TypeScript — это надмножество JavaScript с поддержкой статической типизации, что делает код более надёжным и удобным для сопровождения.

Можно использовать и чистый JavaScript, но это не рекомендуется из-за отсутствия типовой безопасности и сложности масштабирования.

Среда выполнения

Расширения выполняются в среде Node.js, встроенной в VS Code. Это означает, что расширение имеет доступ ко всем возможностям Node.js: файловой системе, сетевым запросам, дочерним процессам и т.д.

Однако важно помнить: расширение работает вне основного процесса редактора (в так называемом extension host), чтобы не блокировать UI при выполнении длительных операций.

API VS Code

VS Code предоставляет мощный Extension API, который позволяет:

регистрировать команды;
создавать пользовательские панели и виджеты;
подписываться на события редактора (открытие файла, сохранение, навигация);
манипулировать текстом в редакторе;
управлять терминалами;
показывать уведомления и диалоги;
интегрироваться с системой отладки;
участвовать в механизмах автодополнения и подсветки синтаксиса.

API организован через модуль vscode, который импортируется в код расширения:

import * as vscode from 'vscode';

Команды и палитра команд

Команда — это зарегистрированная функция, которую можно вызвать из разных частей VS Code: через меню, горячие клавиши, палитру команд или другие расширения.

Каждая команда имеет уникальный идентификатор вида publisher.extension.commandName.

Палитра команд (Command Palette) — это центральный интерфейс вызова команд в VS Code. Вызывается сочетанием клавиш Ctrl+Shift+P (Windows/Linux) или Cmd+Shift+P (macOS). Палитра позволяет быстро найти и выполнить любую доступную команду без необходимости запоминать горячие клавиши или искать пункты меню.

При создании расширения одна из первых задач — зарегистрировать хотя бы одну команду и связать её с действием, которое будет выполняться при вызове.

Возможности расширений

Расширения могут реализовывать широкий спектр функциональности:

Добавление команд — выполнение произвольного кода по запросу пользователя.
Подсветка синтаксиса — определение правил для распознавания и раскраски токенов в новых языках.
Автодополнение — предложение вариантов при вводе кода.
Сниппеты — шаблоны кода, вставляемые по ключевому слову.
Linters и форматтеры — проверка и автоматическое форматирование кода.
Отладчики — интеграция с внешними отладочными движками.
Webview — встраивание HTML/CSS/JavaScript-интерфейсов прямо в редактор (например, для визуализации данных).
Деревья (Tree Views) — создание собственных панелей с иерархическими данными (например, проводник задач, список зависимостей).
Терминалы — запуск и управление консольными процессами.
Тестовые адаптеры — интеграция с фреймворками тестирования.

Установка расширений

Расширения можно установить двумя способами:

Через Marketplace

Это основной способ. Пользователь открывает вкладку Extensions в VS Code (Ctrl+Shift+X), ищет нужное расширение и нажимает Install. Расширение загружается из Visual Studio Code Marketplace.

Через файл `.vsix`

Файл с расширением .vsix — это ZIP-архив, содержащий всё необходимое для установки расширения. Такой файл можно:

скачать с Marketplace вручную;
сгенерировать локально при разработке;
распространять вне официального магазина (например, внутри компании).

Установка .vsix-файла:

Открыть VS Code.
Перейти в Extensions (Ctrl+Shift+X).
Нажать на три точки → Install from VSIX....
Выбрать файл.

Этот способ часто используется для тестирования или внутреннего развёртывания.

Подготовка окружения для разработки

Перед созданием расширения необходимо установить следующие компоненты:

Node.js (рекомендуется LTS-версия, например 18.x или 20.x)
npm (идёт в комплекте с Node.js)
Visual Studio Code
Yeoman и VS Code Extension Generator

Установка Yeoman и генератора:

npm install --global yo generator-code

Yeoman — это инструмент для генерации проектов по шаблонам. generator-code — официальный генератор расширений от Microsoft.

Создание первого расширения

Выполните команду:

yo code

Генератор задаст серию вопросов. Для простого примера ответьте следующим образом:

? What type of extension do you want to create? New Extension (TypeScript)
? What's the name of your extension? HelloWorld
? What's the identifier of your extension? helloworld
? What's the description of your extension? 
? Initialize a git repository? Y
? Which bundler to use? unbundled
? Which package manager to use? npm
? Do you want to open the new folder with Visual Studio Code? Open with `code`

После этого будет создана папка helloworld со следующей структурой:

helloworld/
├── .vscode/
│   └── launch.json          # Конфигурация отладки
├── src/
│   └── extension.ts         # Основной файл расширения
├── package.json             # Метаданные и описание расширения
├── tsconfig.json            # Конфигурация TypeScript
├── README.md
└── vsc-extension-quickstart.md

Разбор ключевых файлов

`package.json`

Это центральный файл любого расширения. Он содержит:

метаданные (название, версию, автора);
зависимости (dependencies, devDependencies);
точку входа (main);
описание активации (activationEvents);
список команд (contributes.commands);
другие возможности (contributes.menus, contributes.keybindings и т.д.).

Пример секции contributes.commands:

"contributes": {
  "commands": [
    {
      "command": "helloworld.helloWorld",
      "title": "Hello World"
    }
  ]
}

А секция activationEvents указывает, когда расширение должно быть загружено:

"activationEvents": [
  "onCommand:helloworld.helloWorld"
]

Это означает: «загрузи расширение только тогда, когда пользователь вызовет команду helloworld.helloWorld».

`tsconfig.json`

Конфигурация компилятора TypeScript. Указывает, как преобразовывать .ts-файлы в .js, какие правила типизации применять, куда выводить результат и т.д.

По умолчанию исходники компилируются в папку out/.

`src/extension.ts`

Основной файл логики расширения. Содержит функцию activate, которая вызывается при активации расширения.

Пример содержимого:

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    let disposable = vscode.commands.registerCommand('helloworld.helloWorld', () => {
        vscode.window.showInformationMessage('Hello, World!');
    });

    context.subscriptions.push(disposable);
}

Здесь:

vscode.commands.registerCommand регистрирует команду с идентификатором helloworld.helloWorld;
при вызове команды показывается информационное сообщение;
context.subscriptions.push гарантирует корректную очистку ресурсов при выгрузке расширения.

Тестирование расширения

VS Code предоставляет встроенную возможность отладки расширений.

Убедитесь, что открыт проект расширения в VS Code.
Нажмите F5 или выберите Run and Debug → Run Extension.
Запустится новый экземпляр VS Code (так называемый Extension Development Host), в котором установлено ваше расширение.
В этом экземпляре откройте палитру команд (Ctrl+Shift+P) и введите Hello World.
Выберите команду — появится уведомление.

Любые изменения в коде требуют перезапуска отладочной сессии (остановить → запустить заново), если не используется горячая перезагрузка (hot reload), которую можно настроить отдельно.

Сборка и подготовка к публикации

Для публикации расширения его нужно упаковать в .vsix-файл.

Сначала установите утилиту vsce (Visual Studio Code Extensions CLI):

npm install -g @vscode/vsce

Затем в корне проекта выполните:

vsce package

Будет создан файл вида helloworld-0.0.1.vsix.

Перед публикацией убедитесь, что в package.json указаны:

publisher (ваш идентификатор на Marketplace);
repository (ссылка на GitHub/GitLab);
license;
иконка (icon) и баннер (galleryBanner) для красивого отображения в магазине.

Для публикации:

Создайте аккаунт на Azure DevOps (Marketplace использует его для аутентификации).
Создайте Personal Access Token (PAT) с областью Marketplace (Publish) и сроком действия.
Выполните:

vsce login <your-publisher-name>
# введите токен
vsce publish

После этого расширение станет доступно в Marketplace.

Публикация расширения в Marketplace

После успешной сборки и тестирования расширения его можно опубликовать в официальном Visual Studio Code Marketplace — централизованном каталоге, доступном миллионам пользователей.

Подготовка к публикации

Перед публикацией необходимо убедиться, что:

В package.json указаны все обязательные поля: name, displayName, description, version, publisher, engines.vscode.
Расширение содержит иконку (icon) и баннер (galleryBanner) для отображения в магазине.
Есть файл README.md с описанием функциональности, скриншотами (если применимо) и инструкцией по использованию.
Указан репозиторий исходного кода (repository.url), лицензия (license) и категории (categories).

Пример секции package.json для публикации:

{
  "name": "helloworld",
  "displayName": "Hello World Sample",
  "description": "A simple Hello World extension for VS Code",
  "version": "0.0.1",
  "publisher": "your-publisher-id",
  "engines": {
    "vscode": "^1.85.0"
  },
  "categories": ["Other"],
  "icon": "images/icon.png",
  "galleryBanner": {
    "color": "#C80000",
    "theme": "dark"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/yourname/helloworld.git"
  },
  "license": "MIT"
}

Создание издателя (publisher)

Marketplace требует регистрации издателя — уникального идентификатора, под которым будут публиковаться все ваши расширения.

Перейдите на Visual Studio Marketplace Management.
Авторизуйтесь через учётную запись Microsoft или GitHub.
Нажмите Publish extensions → Create publisher.
Укажите имя издателя (например, yourname) и контактную информацию.

Это имя будет использоваться как значение поля publisher в package.json.

Генерация токена доступа

Для публикации через командную строку требуется Personal Access Token (PAT):

Перейдите в Azure DevOps Tokens.
Создайте новый токен:
- Organization: All accessible organizations
- Scopes: Marketplace (Publish)
- Срок действия: рекомендуется не более 90 дней.
Сохраните токен — он отображается только один раз.

Публикация через `vsce`

Установите CLI-инструмент vsce, если ещё не установлен:

npm install -g @vscode/vsce

Выполните вход с указанием имени издателя:

vsce login your-publisher-id
# Введите токен при запросе

Опубликуйте расширение:

vsce publish

Команда автоматически:

проверит метаданные;
соберёт расширение;
загрузит .vsix в Marketplace;
присвоит новую версию (если не указана явно).

После публикации расширение становится доступным в течение нескольких минут. Его можно найти по названию в интерфейсе VS Code или на сайте marketplace.visualstudio.com.

Обновление расширения

Для выпуска новой версии:

Измените поле version в package.json согласно SemVer (например, с 0.0.1 на 0.0.2).
Зафиксируйте изменения в системе контроля версий (Git).
Выполните:

vsce publish

Marketplace автоматически обновит страницу расширения, а пользователи получат уведомление об обновлении (если включены автоматические обновления).

Альтернативные способы распространения

Локальная установка (.vsix)

Если расширение предназначено для внутреннего использования (например, в компании), его можно распространять в виде файла .vsix:

Соберите пакет:

vsce package

Передайте файл коллегам.
Они устанавливают его через Extensions → ⋮ → Install from VSIX....

Такой подход не требует публикации в Marketplace и позволяет контролировать доступ.

Приватный Marketplace

Для корпоративных решений Microsoft предлагает Azure DevOps Services с возможностью создания приватного расширения, доступного только членам организации. Это требует настройки Azure DevOps и соответствующих прав доступа.