Создание расширений для visual studio
Другие статьи в серии можно найти здесь:
Создание пакетов расширений (плагинов) для Microsoft Visual Studio IDE на первый взгляд кажется довольно простой задачей. Доступна отличная документация MSDN, а также различные статьи, примеры и множество других источников на эту тему. Но, в то же время, это может показаться сложной задачей, когда на этом пути встречается неожиданное поведение. Хотя можно сказать, что такие проблемы довольно распространены в любой задаче программирования, тема разработки плагинов IDE до сих пор не была полностью рассмотрена.
В этой серии статей мы рассмотрим следующие темы:
- Основная информация о создании и отладке подключаемых модулей MSVS и поддержке этих проектов расширяемости для нескольких версий Visual Studio в общей базе исходного кода.
- Обзор объектной модели автоматизации и различных классов инфраструктуры управляемых пакетов (MPF).
- Информация о расширении интерфейса IDE через классы API объектной модели автоматизации (EnvDTE) и MPF (Managed Package Framework) с помощью пользовательских меню, панелей инструментов, окон и страниц параметров.
- Обзор модели проекта Visual Studio, Atmel Studio IDE, основанной на изолированной оболочке Visual Studio, как пример взаимодействия с пользовательскими моделями проектов сторонних производителей.
- Информация о том, как использовать модель проекта Visual C ++ для сбора данных, необходимых для работы внешнего препроцессора / компилятора, таких как аргументы и параметры компиляции для различных платформ и конфигураций.
Более подробные ссылки на каждую из статей серии доступны в конце каждой статьи со ссылками на библиотеку MSDN и другие внешние ресурсы.
Статьи будут посвящены разработке расширений только для Visual Studio 2005 и более поздних версий. Это ограничение отражает то, что PVS-Studio также поддерживает интеграцию с Visual Studio, начиная только с версии 8 (Visual Studio 2005). Основная причина этого заключается в том, что для Visual Studio 2005 была введена новая модель API расширяемости, и эта новая версия не обратно совместима с предыдущими API расширяемости IDE.
Создание, отладка и развертывание пакетов расширений для Microsoft Visual Studio 2005/2008/2010/2012
Этот элемент содержит обзор нескольких различных методов расширения функциональных возможностей Visual Studio IDE. Создание, отладка, регистрация и развертывание пакетов расширений Visual Studio для конечных пользователей будут подробно объяснены.
Создание и отладка модулей расширения VSPackage для Visual Studio и Visual Studio Isolated Shell
В более ранних версиях плагин PVS-Studio (точнее, версии 1.xx и 2.xx, когда он еще назывался Viva64) существовал как пакет надстройки. Начиная с PVS-Studio 3.0, он был переработан как VSPackage, потому что функциональность, которую могла обеспечить надстройка, стала недостаточной для выполняемых задач, а также процесс отладки был довольно неудобным. В конце концов, мы хотели иметь собственный логотип на заставке Visual Studio!
VSPackage также предоставляет средства для расширения самой модели автоматизации, регистрируя в ней определенные пользователем объекты автоматизации. Такие объекты автоматизации пользователей станут доступны через ту же модель автоматизации для других пользовательских пакетов расширения, предоставляя этим пакетам доступ к вашим пользовательским компонентам. Это, в свою очередь, позволяет сторонним разработчикам добавлять поддержку новых языков программирования и компиляторов через такие расширения в IDE, а также предоставлять интерфейсы для автоматизации этих новых компонентов.
Помимо расширения самой среды Visual Studio, расширения VSPackage можно использовать для добавления новых функций в изолированные \ интегрированные оболочки Visual Studio. Изолированные \ интегрированные оболочки предоставляют любому стороннему разработчику возможность повторно использовать базовые компоненты интерфейса и службы Visual Studio (такие как редактор кода, система автозаполнения и т. Д.), А также реализовывать поддержку других пользовательских моделей проектов. и \ или компиляторы. Такой дистрибутив не будет включать ни один из проприетарных языковых модулей Microsoft (таких как Visual C ++, Visual Basic и т. Д.), И он может быть установлен конечным пользователем, даже если его или ее система не содержит предыдущей установки Visual Studio.
После установки изолированное приложение оболочки останется отдельным объектом, даже если система содержит предыдущую установку Visual Studio, но интегрированное приложение оболочки будет объединено в предустановленную версию. В случае, если разработчик изолированной \ интегрированной оболочки расширяет модель автоматизации Visual Studio, добавляя интерфейсы к своим пользовательским компонентам, все остальные разработчики расширений VSPackage также смогут обрабатывать такие компоненты. Atmel Studio, IDE, разработанная для разработки встраиваемых систем, является примером приложения Visual Studio Isolated Shell. Atmel Studio использует собственную модель проекта, которая, в свою очередь, сама является реализацией стандартной модели проекта Visual Studio для MSBuild и конкретной версии компилятора GCC.
Проекты для подключаемых модулей VSPackage: создание пакета расширения
Давайте рассмотрим создание плагина пакета Visual Studio (расширение VSPackage). В отличие от дополнительных модулей, разработка пакетов расширений VS требует установки Microsoft Visual Studio SDK для целевой версии IDE, то есть отдельный SDK должен быть установлен с каждой версией Visual Studio, для которой разрабатывается расширение. В случае расширения, предназначенного для Visual Studio Isolated \ Integrated Shell, потребуется SDK для версии Visual Studio, на которой основана такая оболочка.
Мы будем изучать разработку расширений для изолированных версий оболочек Visual Studio и Visual Studio 2010 на основе версий 2005, 2008, 2009 и 2012 годов. При установке Visual Studio SDK в диспетчер шаблонов VS добавляется стандартный шаблон проекта для пакета Visual Studio (на странице «Другие типы проектов -> Расширяемость»). Если этот параметр выбран, этот шаблон будет генерировать базовый проект MSBuild для пакета расширения, позволяя заранее указать несколько параметров, таких как язык программирования, и автоматически генерировать несколько компонентов-заглушек для общих элементов пользовательского интерфейса, таких как элементы меню. редактор, окно инструментов пользователя и т. д.
Основной класс пакета расширения должен быть унаследован от пакета Microsoft.VisualStudio.Shell.Package . Этот базовый класс предоставляет управляемые оболочки для API-интерфейсов взаимодействия IDE, реализация которых требуется из полнофункционального пакета расширений Visual Studio.
Класс Package позволяет переопределять его базовый метод Initialize. Этот метод получает управление выполнением в момент инициализации пакета в текущем сеансе IDE.
Инициализация модуля будет происходить, когда он вызывается в первый раз, но он также может запускаться автоматически, например, после запуска IDE или когда пользователь входит в предварительно определенное состояние контекста пользовательского интерфейса среды.
Отладка пакетов расширения: экспериментальный экземпляр
Задача отладки подключаемого модуля или расширения, предназначенного для IDE, не является тривиальной. Довольно часто такая среда сама используется для разработки и отладки плагина. Подключение нестабильного модуля к этой IDE может привести к нестабильности самой среды. Необходимость удаления разрабатываемого модуля из среды IDE перед каждым сеансом отладки, что, в свою очередь, часто требует его перезапуска, также является серьезным неудобством (среда IDE может заблокировать библиотеку DLL, которая должна быть заменена более новой версией для отладки).
Следует отметить, что процесс отладки VSPackage в этом аспекте существенно проще, чем в пакете надстроек. Это было одной из причин изменения типа проекта плагина PVS-Studio.
VSPackage решает вышеупомянутые проблемы разработки и отладки, используя механизм экспериментального экземпляра Visual Studio. Такой экспериментальный экземпляр можно легко запустить, передав специальный аргумент командной строки:
Экспериментальный экземпляр среды использует отдельный независимый куст реестра Windows (так называемый экспериментальный куст) для хранения всех своих настроек и данных регистрации компонентов. Таким образом, любые изменения в настройках среды IDE или изменения в регистрационных данных ее компонентов, которые были сделаны внутри экспериментального куста, не будут влиять на экземпляр, который используется для разработки модуля (это ваш основной регулярный экземпляр, который используется по умолчанию).
Visual Studio SDK предоставляет специальный инструмент для создания или сброса таких экспериментальных экземпляров: CreateExpInstance . Чтобы создать новый экспериментальный улей, он должен быть выполнен с этими аргументами:
Выполнение этой команды создаст новый экспериментальный куст реестра с суффиксом PVSExp в его имени для 10-й версии IDE (Visual Studio 2010), а также предварительно сбросит все его настройки до значений по умолчанию. Путь к реестру для этого нового экземпляра будет выглядеть следующим образом:
Хотя суффикс Exp используется по умолчанию для отладки пакетов внутри проекта шаблона VSPackage, другие экспериментальные ульи с уникальными именами также могут быть созданы разработчиком по желанию. Чтобы запустить экземпляр среды для улья, который мы создали ранее (содержащего PVSExp в его имени), следует использовать следующие аргументы:
Возможность создания нескольких различных экспериментальных ульев на одной локальной рабочей станции может быть весьма полезной, например, для обеспечения одновременной и изолированной разработки нескольких пакетов расширений.
Эта статья продолжает небольшую серию «Создаём ваш первый плагин для…», в которую уже вошли статьи про написания плагина для Grunt и Gulp.
Дисклеймер
Я люблю JavaScript. Мне довольно приятно наблюдать за тем, что этот прекрасный язык программирования вышел за пределы браузера и собирает всё больше и больше областей применения. Так, например, благодаря Electron от GitHub у меня появилось сразу несколько приложений, которые я использую в повседневной жизни. К таким приложениям относится Hain, 1Clipboard, Wagon, Gitify и, конечно же, Visual Studio Code.
Теперь поговорим о приятном для некоторых людей и противном для других. У меня нет симпатий к TypeScript. На то есть свои причины, в основном, связанные с типизацией — не люблю я её, что тут поделать. При этом я не буду отрицать, что когда-нибудь начну использовать TypeScript или подобный язык, компилируемый в JavaScript — всё бывает, мнение может меняться со временем. Однако, в связи с этим, в статье все примеры будут написаны на JavaScript, хотя сам редактор и вся документация к нему написана с применением TypeScript в примерах.
Что-то вместо введения
Герой нашего дня (VS Code) построен на Electron, который подробно рассматривался в статье «Построение Electron приложения. Введение». На момент написания статьи (июнь 2016) в основе редактора лежит Electron версии 0.37.6, что подразумевает под собой Chromium 49-ой ветки и Node.js версии 5.10.0. В репозитории на GitHub уже думают над переходом на новую версию Electron, где версия Chromium поднимется минимум до 51-ой ветки, а Node.js до версии 6.1.0 или выше. Всё это означает, что вы можете писать плагины, используя синтаксис ES2015 без Babel и его альтернатив, а также применяя любой API Node.js.
Предупреждение
Не стоит читать эту статью дальше введения, если вы не понимаете фишки, введённые в ES2015. Если говорить конкретно, то от вас требуется понимание деструктуризации, обещаний, стрелочных функций, const и let, а также понимание основ Node.js.
Итак, пожалуй, начнём с того, что плагины в VS Code изолированы от самого редактора и запускаются в отдельном хост-процессе (extension host process), который представляет собой процесс Node.js с возможностью использования VS Code API. Такой подход не позволяет плагинам влиять на производительность редактора при его запуске или в процессе его работы. Для пользователя это означает, что редактор не зависнет на время выполнения задач каким-либо плагином или, если плагин выдаст фатальную ошибку.
Для экономии расхода памяти разработчики также добавили ленивую загрузку плагинов. Это означает, что плагины активируются лишь в тот момент, когда они нужны. Например, если пользователь открывает Markdown-файл, то плагины, работающие с Markdown, будут загружены только в момент открытия файла. Разумеется, мы должны сообщить редактору о том, когда именно он должен активировать какой-либо плагин. О настройке ленивой загрузки мы поговорим позднее в разделе про файл манифеста.
Помимо всего прочего, плагины делятся на три вида в зависимости от функционала:
К первому виду относятся стандартные плагины, которые запускаются в хост-процессе, активируются в нужный момент и не требуют серьёзных вычислений.
Ко второму виду относятся так называемые «языковые серверы». Клиентская часть плагина запускается в хост-процессе, а серверная часть создаёт дополнительный процесс, в котором производятся все сложные вычисления. К такому виду плагинов относятся линтеры.
К третьему виду относят «службы отладки», которые пишутся в виде отдельной программы и взаимодействуют с VS Code по специальному протоколу CDP (VS Code Debug Protocol).
В этой статье будет рассматриваться лишь первый вид плагинов на примере vscode-lebab. Во второй статье разбирается процесс построения второго вида плагинов на примере vscode-puglint.
Манифест плагина
Написание плагина начинается не с кода, а с файла манифеста, которым в мире Node.js является файл package.json . VS Code дополняет стандартный файл манифеста своими полями. Ниже будут рассмотрены самые основные из них.
publisher [string]
Имя пользователя, под которым вы зарегистрировались в vsce.
icon [string]
Путь до иконки, которая будет отображаться в магазине расширений. Размер иконки 128x128 пикселей. Также поддерживается SVG формат.
displayName [string]
Название плагина, которое будет отображаться в магазине расширений.
categories [array]
Массив, содержащий имена категорий, к которым относится плагин. Доступны следующие категории: [Languages, Snippets, Linters, Themes, Debuggers, Other] . Пожалуйста, указывайте категорию или категории обдуманно. Например, если ваше расширение включает в себя подсветку синтаксиса языка и сниппеты, то указывайте только эти две категории.
galleryBanner [object]
Настройки оформления страницы расширения в магазине. Используется для того, чтобы иконка расширения и фон подложки были контрастны. Свойство color отвечает за цвет фона, свойство theme за цвет шрифта: dark — белый, light — чёрный.
preview [boolean]
activationEvents [array]
Массив событий, в случае наступления которых плагин будет активирован редактором. Поддерживаются следующие события, активирующие плагин в том случае, если будет:
- onLanguage — открыт файл указанного языка (не расширения).
- onCommand — вызвана указанная команда.
- onDebug — запущен сеанс отладки указанного типа.
- workspaceContains — найден указанный файл в корневой папке проекта.
Отдельно стоит отметить событие * , которое активирует плагин при загрузке редактора. Однако, использовать это событие нужно крайне редко и в том случае, если комбинации других событий не могут решить сложившуюся проблему.
contributes [object]
С помощью этого поля в package.json разработчик описывает своё расширение. Доступно довольно большое количество всевозможных полей, описывающих:
- configuration — поля, доступные пользователю в настройках редактора.
- commands — команды, доступные пользователю в палитре команд F1 .
- keybindings — сочетания клавиш для вызова команд.
- languages — языки.
- debuggers — отладочный адаптер.
- grammars — TextMate-грамматику, необходимую для подсветки синтаксиса.
- themes — темы.
- snippets — сниппеты.
- jsonValidation — схемы проверки определённых JSON-файлов.
Несложно догадаться, что поля необходимо указывать в зависимости от типа вашего расширения. Если это плагин, сортирующий строки, то, вероятнее всего, вы будете использовать поля: configuration , commands и keybindings .
extensionDependencies [array]
Немного про VS Code API
Как и полагается любому крупному проекту, VS Code имеет довольно обширный API, доступный разработчикам плагинов. Рассмотрим лишь так называемые пространства имён:
Пишем стандартный плагин
Постановка задачи
В этой части статьи я буду описывать процесс написания плагина для VS Code на основе lebab, который автоматически конвертирует JavaScript-код, написанный по стандарту ES5 в ES2015. Это проект является альтернативой проекту Babel, но в обратную сторону.
Манифест
И снова скажу, что написание плагина начинается не с кода на JavaScript, а с манифеста. Первым делом создаём файл package.json и пишем туда пару десятков строк, описывающих плагин. Полный листинг манифеста вы сможете найти в репозитории плагина vscode-lebab. Остановимся именно на тех моментах, которые касаются работы с VS Code.
Во-первых, укажем информацию, которая будет отображаться в маркете:
Во-вторых, укажем массив событий, на которые наш плагин должен откликаться. Про команду lebab.convert я расскажу немного позднее.
В-третьих, опишем плагин. Предполагается, что пользователю будет доступна лишь одна команда, по вызову которой он получит сконвертированный ES5-код в синтаксис ES2015. Также предполагается, что в настройках редактора пользователь сможет указать, что именно он хочет конвертировать с помощью lebab. Для этого я определил опцию lebab.transforms , содержащую объект ключей, с которыми будет работать конвертер.
Убираем из маркета лишнее
Сколько раз не говори, но я всё равно встречаю модули в npm, у которых вместе с кодом я получаю файлы тестов, изображений и прочей лабуды. К счастью, теперь я могу ссылаться на эту статью в отношении npm. В случае VS Code, необходимо создать файл .vscodeignore , который действует так же, как и файл .gitignore , но в отношении маркета расширений.
У меня файл .vscodeignore имеет следующее содержимое:
Я очень прошу, убирайте всё лишнее из плагина, иначе я вас вычислю по IP и накажу.
Базовый код
В мире Node.js принято писать код модуля в файле index.js , а приложения — app.js . Мир VS Code тоже имеет традиции, и код плагина пишется в файле extension.js .
Внимание
Если очень хочется писать код в файле с именем, отличным от extension.js , то, как и в мире Node.js, вам придётся указать имя файла в поле main в манифесте.
Для начала определим две функции. Первая функция будет иметь имя activate и вызываться в том случае, если плагин был активирован событием, указанным в манифесте. Вторая функция имеет имя deactivate и вызывается в том случае, если плагин был деактивирован. Под деактивацией следует понимать последействие команды, а не удаление плагина. Её предназначение в большинстве плагинов излишне, поэтому она не обязательна. Далее в статье я не буду упоминать функцию деактивации плагина.
Напомню, что в файле манифеста была указана команда lebab.convert — самое время её зарегистрировать. Для регистрации команд существует два метода:
- registerTextEditorCommand — регистрирует команду в контексте текстового редактора или файла.
- registerCommand — регистрирует команду в глобальном контексте, то есть вне зависимости от наличия открытого редатора с текстом.
Второй метод используется крайне редко, вследствие того, что, в основном, плагины нацелены на работу с содержимом текстового редактора.
В конце все объявленные команды должны быть добавлены в массив subscriptions .
При регистрации команды необходимо передать идентификатор команды, указанный в файле манифеста и функцию обратного вызова, в которую передаётся объект textEditor , содержащий всю информацию о текущем редакторе, такую как:
- Файл на диске или новый файл (untitled)
- Путь до файла и его имя
- Идентификатор языка
- Наличие EOL
- Если было выделение текста, то параметры этого выделения
- Статистика текста (количество символов в строке и прочее)
- Версия файла (проще говоря, номер сохранения в истории файла)
- Строки файла
- и т.д.
Чисто практически, вы можете обращаться к свойствам объекта и работать с полученными из него данными. Но, разумеется, лучше всего обращаться к этому объекту с помощью определённых методов. На данном этапе нам нужно получить текст файла, чтобы в дальнейшем обработать его, и настройки, определённые в редакторе для нашего плагина.
Получить текст открытого документа можно, используя метод getText , а настройки, используя метод getConfiguration у workspace API:
Внимание
Настройки редактора нужно получать в момент вызова команды, иначе, если получить их в момент активации плагина, то при обновлении настроек редактора, объект в переменной не обновится.
Далее я не буду рассматривать процесс вызова Lebab, потому что это элементарное действие, не относящееся к VS Code. Покажу лишь тот участок, что отвечает за вставку обработанного текста обратно в окно редактора. Для этого мы обратимся к объекту textEditor и вызовем метод edit с коллбэком, представленным ниже. Конечно же, код должен располагаться после получения текста документа и настроек редактора в функции обратного вызова регистрации команды.
Собственно, это всё, что требуется сделать в обычном плагине для VS Code: получить текст, обработать его и вернуть обратно. Полный листинг кода содержит 52 строки и размещён на GitHub в репозитории vscode-lebab.
Как можно заметить, ничего сложно — простейший JavaScript-код, который разбавлен вызовами необходимых API редактора. В этой статье был рассмотрен простейший случай, когда у вас есть готовое решение и его нужно подружить с редактором. В случае, если готового решения нет, то лучше оформить его в виде npm-пакета по всем канонам (тесты, документация), а уже потом подружить его с редактором. В качестве примеров, если решите писать плагин на JavaScript, вы можете посмотреть код следующих плагинов:
Что-то вместо вывода
В этой статье я помог вам начать писать плагины для VS Code. Многое осталось за кулисами и не рассматривалось, однако вам в любом случае придётся обращаться к документации. Считайте, что эта статья преследует цель показать, что писать плагин для VS Code довольно просто, причём необязательно делать это на TypeScript. Хотя, при этом не стоит забывать, что TypeScript — это всё тот же JavaScript.
Также, советую посмотреть на код, представленный в репозитории VSCode-Sample. Здесь автор собрал примеры взаимодействия с UI редактора, которые, возможно, помогут вам освоиться.
Если вам интересна тема разработки плагинов для VS Code, то добро пожаловать во вторую часть этой статьи, в которой рассматривается процесс написания плагина, использующего языковой сервер.
Что почитать?
Делимся на оплату хостинга или кофе.
Чем чаще пью кофе, тем чаще пишу статьи.
Visual Studio Code – это редактор кода от Microsoft, доступный для систем Windows, Linux и macOS. Для внедрения дополнительных функций он предлагает готовые расширения, которые вы можете установить через Visual Studio Code Marketplace. Но если вы не можете найти расширение, которое делает именно то, что вам нужно, вы можете создать необходимое расширение самостоятельно.
В этом руководстве вы узнаете, как создать свое первое расширение Visual Studio Code.
Требования
Для выполнения этого урока нужно:
- Загрузить и установить последнюю версию Visual Studio Code.
- Установить Node.js. Инструкции по установке зависят от дистрибутива: Mac OS, Ubuntu, CentOS, Debian.
Это руководство было проверено на версиях Node v14.4.0, npm v6.14.5, yo v3.1.1 и generator-code v1.2.16.
1: Установка инструментов
Команда Visual Studio Code разработала специальный генератор для создания расширений. Он генерирует все необходимые стартовые файлы, чтобы вы легко могли начать создание вашего расширения.
Чтобы начать разработку расширений VS Code, вам понадобятся два пакета npm:
Используйте встроенный терминал Visual Studio Code, чтобы при помощи npx запустить локальные копии yo и generator-code, а затем введите команду yo code для инициализации вашего нового проекта:
npx -p yo -p generator-code yo code
После этого Yeoman запустит генератор кода.
2: Создание расширения
Сейчас вам нужно будет ответить на несколько вопросов о проекте: указать, какое расширение вы создаете, а также выбрать между TypeScript и JavaScript. В этом уроке мы выберем JavaScript.
Затем вам будет предложено еще несколько вопросов. В этом мануале мы выбрали следующие ответы:
После завершения этого процесса вы получите все файлы, необходимые для начала работы. Два самых важных файла:
Откройте package.json и взгляните на его содержимое. Вы увидите название, описание проекта и т.п. В нем есть два очень важных раздела.
Мы вернемся к ним в ближайшее время.
Вы также можете просмотреть файл extension.js. В нем мы напишем код для нашего расширения. Здесь уже есть шаблонный код, давайте разберемся с ним.
В выделенной ниже строке мы регистрируем в VS Code нашу команду. Обратите внимание, что имя helloWorld совпадает с именем команды в package.json. Это не случайно. Пакет package.json определяет, какие команды доступны пользователю, но файл extension.js регистрирует код для этой команды.
3: Отладка расширения
Теперь, когда все необходимые файлы установлены, мы можем запустить наше расширение.
Папка .vscode – это место, где VS Code хранит конфигурационные файлы проекта. В нашем случае он включает файл launch.json, содержащий конфигурации отладки.
В этом файле проводится отладка расширения. Откройте вкладку debug в левой части экрана, а затем кликните на плей.
Это откроет новый (отладочный) экземпляр VS Code.
Открыв его, вы можете развернуть палитру команд (с помощью Command + Shift + P на Mac или Ctrl + Shift + P в Windows) и запустить Hello World.
4: Редактирование расширения
Прежде чем приступить к работе над кодом, давайте еще раз взглянем на раздел activateEvents в файле package.json. Как вы уже знаете, этот раздел содержит список событий, которые активируют наше расширение всякий раз, когда происходят. По умолчанию расширение активируется при запуске нашей команды.
Теоретически это событие может быть любым (что определяется символом *). Если установить для события активации значение *, то ваше расширение будет загружено при запуске VS Code.
Примечание: Этого делать не нужно, это просто комментарий.
Итак, у нас есть необходимые файлы и мы знаем, как их отлаживать. Приступим же к созданию нашего расширения. Предположим, мы хотим, чтобы это расширение создавало HTML-файл, который содержит шаблонный код и добавляется в наш проект.
Сначала давайте обновим название нашей команды. Откройте extension.js и обновите имя команды с extension.helloworld на extension.createBoilerplate.
Соответствующим образом обновите package.json:
Теперь напишем наш функционал. Первое, что нужно сделать, это потребовать пару пакетов. Мы будем использовать модули fs (file system) и path. В файл extension.js поместите:
Также нам нужно получить путь к текущей папке. Внутри раздела command поместите следующий фрагмент:
Нам также нужно присвоить шаблонный HTML-код переменной в файле extension.js, чтобы он автоматически записывался в файл. Вот этот шаблонный HTML:
Теперь нужно вызвать функцию writeFile модуля файловой системы и передать ее в пути к папке и HTML-коде.
Обратите внимание, мы используем модуль path, чтобы объединить путь к папке с именем файла, который мы хотим создать. Если внутри обратного вызова есть ошибка, мы отображаем ее пользователю. В противном случае расширение сообщает, что шаблонный файл успешно создан:
Вот как выглядит полный код extension.js:
Попробуйте выполнить отладку вашего нового расширения. Откройте палитру команд и запустите Create Boilerplate (помните, мы изменили имя).
Заключение
Чтобы узнать больше о том, какие API можно использовать и как именно их использовать, прочтите документацию по API от Visual Studio.
Создание сниппета или цветовой темы в VS Code - это хорошо, но что если вы создали что-то настолько хорошее, что можно было бы показать другу или, что еще лучше, предоставить к ипользованию сообществу. Для этого у нас есть Visual Studio Marketplace. В этой статье мы создадим расширение и доведем его до Marketplace, чтобы люди могли загружать его прямо себе в VS Code. Вскоре вы станете создателем расширения.
Эта статья будет охватывать следующее темы:
- scaffold расширение проекта
- напишем расширение, в данном случае речь идет о написании сниппета
- публикуем расширение для Visual Studio Marketplace
Итак, мы уже создали сниппет в первой части «Создание снипппета».
Пришло время сделать следующий шаг, давайте поделимся наши творением со всем миром. И как же мы поступим? На самом деле все это можно сделать всего лишь за три основных шага:
Конечно, у каждого из этих шагов есть много подшагов, но не волнуйтесь, я все подробно объясню и в конце этой статьи, когда у вас все получится, вы будете радоваться примерно так:
Ресурсы
Мы расскажем, как создать расширение с помощью шаблона Snippets, но вы также можете создать еще очень много других расширений, поэтому вот несколько ссылок, которые помогут вам узнать чуточку больше:
Scaffold расширяемого проекта
Для этого есть scaffolder, который позволяет создавать проект за секунду. Для установки scaffolder просто наберите:
Чтобы создать дополнительный проект, просто наберите:
Далее вы увидите диалоговое окно, в котором нужно задать некоторые необходимые параметры. Рассмотрим каждый экран и разберемся в настройках:
Из множества вариантов приведенных выше, мы выберем вариант New Code Snippets .
Затем мы получаем диалог с просьбой выбрать между импортом существующих сниппетов из папки или создать новый импорт:
Мы выбираем создание нового и поэтому просто нажимаем на return клавишу. Далее нужно будет дать нашему расширению имя. Именно это имя будет указываться в торговой площадке Visual Studio, поэтому давайте дадим ему достойное имя, например, вот так:
Далее последует вопрос, который по сути будет выполнять роль идентификатора. Мы просто нажали клавишу return . Это означает, что имя и идентификатор будут одним и тем же:
Следующим шагом становится печать издателя. Сейчас вы, наверное, думаете "Какой издатель, о чем он говорит, и что хочет от меня? Ну а пока придумайте имя для издателя, позже мы его создадим и зарегистрируем на торговой площадке Visual Studio, всему свое время :)
Вы можете увидеть, что в качестве издателя я уже ввел значение chris noring , т.к я создал издателя заранее, а если вы еще не создали, то сделайте это прямо сейчас.
Следующий шаг состоит в том, чтобы ввести идентификатор языка, тем самым явно указать для какого языка этот сниппет. Давайте введем javascript или typescript , не забудьте ввести его маленькими буквами, как указано в инструкции:
Наконец все готово!. Далее, вы должны увидеть файлы, которые создадутся для вашего расширения, например:
Расширяем анатомию проекта
Итак, теперь мы наконец то можем посмотреть, что за проект у нас получился в целом:
Наш проект состоит из следующих папок и файлов (начиная с самого верха):
- /snippets/snippets.json, то место, где создаются наши сниппеты и где мы будем проводить большую часть нашего времени
- README.md, содержит информацию о вашем проекте. Вам необходимо добавить специальную информацию, чтобы иметь возможность публиковать расширение для торговой площадки Visual Studio. Так какую информацию здесь разместить? Начнем с того, что вы должны сказать пользователю, какие команды он будет иметь в своем распоряжении после установки этого расширения. Также хорошо, если вы предоставите пользователю историю всех различных версий и того, что они содержат. Это покажет пользователю, что вы очень заинтересованы в улучшении расширения с течением времени.
- ../.yo-rc.json, теперь этот файл находится за пределами проекта и содержит имя издателя, менять его не нужно
- package.json, содержит метаинформацию о проекте. Здесь важно изменить свойство версии и увеличивать его по мере обновления и повторной публикации проекта
Итак, теперь мы немного больше понимаем, какие файлы важны и куда идти, чтобы что-то менять, если это необходимо.
Создаем наши сниппеты
Хотите верьте, хотите нет, но это самая легкая часть. В первой статье этой серии мы уже объяснили, как создавать сниппеты, так что здесь лишь закрепим материал. Посмотрите еще раз, как у нас создаются несколько сниппетов:
Отлично, теперь у нас есть сниппет. Идем дальше!
Тестируем наши сниппеты
Чтобы использовать и протестить сниппет, нам нужно сначала его установить. Для его установки нам нужно сделать следующее:
- запустить package команду run
- установить его из командной строки
- протестировать в подходящем файле
Итак, начнем с запуска package команды в терминале. Для этого нам нужно добавить зависимость:
Ах, и сразу получаем ошибку, не правда ли хорошее начало? На самом деле эта ошибка оказалась весьма полезной, т.к она говорит нам о том, что пользователь этого расширения заслуживает лучшего, а именно хорошо сформулированного и продуманного файла README.me, который бы давал исчерпывающую информацию об этом расширении. Итак, давайте отправимся к файлу README.md и позаботимся о его содержимом.
Здесь много чего написано, но что вам действительно нужно изменить, так это вот этот текст: This is the README , на самом вверху. Как только закончим редактирование, мы можем попробовать запустить команду run заново. Считаю, что в файле README имеет смысл дать начальное описание и расставить заголовки, такие как Features и Release Notes . Features . Функции, на мой взгляд, должны описывать все доступные команды и то, что они делают. Примечания к выпуску должны содержать журнал истории каждого выпуска и его влияние, например, исправление ошибки или добавление сниппета.
Итак, как только мы грамотно оформим README файл, можем снова запустить package команду run:
Скорей всего программа будет ругаться на то, что мы пропустили свойство repository в нашем файле package.json. Вообще, для того, чтобы это работало нам не нужен репозиторий, вполне хватит того, что у нас уже есть. Итак, мы продолжим, нажав y . Теперь следует сказать, что создался установочный файл:
Когда у нас есть такой файл, мы готовы установить расширение локально в нашей среде. Это позволит нам протестировать наше расширение, чтобы убедиться, что все работает как мы и задумывали. Чтобы установить его, мы должны открыть командное окно. Для этого перейдите в View => Command Palette. Затем начните вводить «VSIX». Должно появиться следующее:
Давайте выберем эту команду. Появиться диалоговое окно выбора файла, в котором вам нужно выбрать недавно созданный файл vsix. После этого VS Code должен спросить вас, хотите ли вы перезагрузить VS Code. После нажатия yes ваша среда IDE готова к тестированию.
Если вы видите у себя на мониторах, то же самое, что и здесь, это означает, что ваш сниппет работает так, как и было задумано и мы можем поставить себе твердую пятерку. Мы приближаемся к Visual Studio Marketplace и славе разработчиков;)
Публикуем сниппеты
Итак, настал тот момент, которого так долго мы все ждали. Пришло время опубликовать это расширение и увидеть свое имя в неоновом цвете на торговой площадке Visual Studio :)
Помните, как в начале создания нашего проекта расширения нам было предложено указать имя издателя? Что ж, теперь пришло время создать этого издателя. И как же нам это сделать?
Нам нужно создать учетную запись с помощью ссылки Visual Studio Team Service link to VSTS. После того, как мы создали учетную запись здесь, нам нужно получить токен доступа.
Создание токена доступа
Токен доступа необходим, когда мы публикуем наше расширение, используя vsce в терминале. Чтобы создать токен доступа, нужно зайти на нашу VSTS страницу, нажать на профиль в правом верхнем углу и выбрать пункт меню «Security». Оказавшись там, нам нужно:
- выберите «Personal Access Tokens».
- Следующим шагом будет выбор создания нового такого токена.
- Присвойте ему подходящее имя и дату окончания срока действия, а так же важно в раскрывающемся списке организации выбрать « All accessible organizations », иначе он не будет работать. Следующее важное поле - области применения Scopes . Здесь вы можете использовать либо пользовательский custom defined , либо полный доступ full access . Если вы в первый раз пробуете это сделать, то попробуйте сейчас получить полный доступ full access , но не забудьте позже отозвать этот токен, выбрать пользовательский custom defined и установить для него наименьшее количество привилегий. Обычно хватает того, чтобы у него были расширения и доступ к рынку.
Итак, пройдя весь этот путь, мы должны увидеть токен доступа, который можно скопировать в буфер обмена.
Обязательно скопируйте его в подходящее место для последующего поиска, т.к он не будет отображаться снова, после закрытия диалогового окна.
Обновить токен
Рано или поздно срок действия токена закончится. Когда это произойдет, восстановите свой токен и запустите его в терминале:
Теперь будет использоваться ваш новый токен, поэтому при следующей команде вы будете вводить только:
Публикуем
Хорошо, наконец-то мы готовы запустить команду публикации. Пришло время к запуску:
Это команда отправит наше расширение в Visual Studio Marketplace. Запустив команду в терминале, она должна показать что-то вроде этого:
Наслаждайтесь плодами своего труда
Вот здесь есть чему гордиться!. Вот оно, ваше расширение во всей своей красе, доступное всему миру. Давайте покажем, что это так, выполнив поиск по вкладке расширений в коде Visual Studio:
Вот оно, вы ввели имя вашего расширения, код Visual Studio показал его вам. Вы можете как родитель для вашего расширения и, конечно же, родители гордятся своими детьми. Давайте также посмотрим на страницу с подробностями, т.е зайдем в файл README:
Вот он! И это только начало нашего пути. Теперь выходите и создавайте расширения заново, я знаю, что вы можете сделать это .
Улучшить расширение
Есть две основные вещи, над которыми стоит поработать, чтобы улучшить восприятие вашего расширения людьми:
- добавить репозиторий
- добавить превью
Добавление репозитория
Чтобы добавить репозиторий, создайте его на GitHub. Как только это будет сделано, давайте добавим его в наш файл package.json:
Вот и все, теперь он будет отображаться на странице расширения, и люди смогут кликнуть и перейти к вашему репо и посмотреть, как вы создавали его, и если захотят, могут помочь вам с этим, отправляя пулл-риквесты.
Добавление превью GIF
Если вы скачали расширения раньше, вы, возможно, заметили, что некоторые из них получаются действительно профессиональными с вступительным видео, демонстрирующим все возможности. В действительности это GIF и добавить ее довольно просто:
Обратите внимание на то, как мы ссылаемся на изображение каталога. Он сможет решить эту проблему, заглянув в ваш репозиторий и ожидая найти этот каталог изображений. Вот почему вам нужно установить репозиторий, чтобы это работало. Нет репозитория, нет предварительного изображения.
Ваша торговая площадка теперь будет выглядеть примерно так:
Выше приведено статическое изображение, поэтому в посте оно не будет отображаться как анимация, но работать будет по-настоящему.
Я рекомендую создать необходимое видео с помощью Camtasia или какой-нибудь бесплатной опции, а затем конвертировать его в gif, как только вы закончите запись.
Резюмируя
В итоге мы узнали следующее:
- Создали проект расширения, используя скаффолдер
- Добавили несколько фрагментов в наш проект
- Протестировали наш сниппет локально, чтобы убедиться, что он работает, прежде чем публиковать
- Настроили для публикации, установив vsce и сгенерировав токен доступа
- Любовались нашим прекрасным творением в Visual Studio Marketplace
- Поделились с сообществом хорошим рабочим решением
Иди и покажи сообществу, что ты можешь и какие проекты у тебя есть.. Хотите рассказать мне об этом? Просто отправьте твит на @chris_noring
Немного обо мне
Сейчас у меня выложено несколько расширений сниппета, которые я активно поддерживаю. Пишите отзывы.
Читайте также: