marvinav / tfs-extension-template

Шаблон проекта для создания расширения для Team Foundation Server и Azure.

Установка

1. Перейти в директорию репозитория и выполнить скрипт npm run build. После выполнения скрипта будет сформирован файл {Extension Id}-{Version} в директории dist/prod, где Version - это номер версии.
2. Загрузить файл расширения на TFS через market place или локально через _gallery/manage.

Разработка

Чтобы можно было дебажить свой плагин на стенде без повторной загрузки исправленного расширения через менеджер расширения, с source map и react-devtools, нужно настроить vss-extension отдельно для dev и prod. Для dev можно оставить всё то же самое, что и для prod, но только добавить обязательно baseUri https:\localhost:{port}. Но мне кажется удобнее, разделять версию плагина, собранного для prod и для dev, чтобы они отличались не только итерацией версий, но и id. В этом репо я использую суфикс -dev. Также, ещё одно отличие prod от dev заключается в упаковке расширения, а именно нужно использовать разный bundle. Для прода, собранный с режимом production, для dev: собранный в режиме development и sourceMap. Для этого выделено два отдельных Webpack.{ENV}.js для dev и prod. В webpack.dev.js также настроен dev-server и source mapping. Чтобы можно было дебажить свои исходники. Также, поскольку расширение запускается в iFrame, react development tools не хочет работать. Для этого необходимо в index.html самым первым тегом script в заголовке указать адрес http:\localhost:8097. Важно не забыть при деплое в прод убрать этот тег. К сожалению, расширения для браузера не хотят работать с этим. Но на помощь приходит npm install -g react-devtools@^3. Есть 4 версия, но у меня на трёх компьютерах запускается битой. Запускаете через терминал react-devtool, обновляете страницу плагина и он начнёт выводить состояния и свойства компонентов.
Ниже полный алгоритм, который проверен на chrome, msedge и firefox на трёх разных компах и везде работает одинаково. Это расширение написано в стеке webpack-react-typescrpit-babel(polyfill). Babel(polyfill), чтобы работало в IE. В принципе, последнии три можно варьировать, просто надо будет подправить под себя Webpack.js. Структура проекта:

• src //Исходники
• dist // Сборки для установки
• dist/test/deploy // Распакованный vsix, который прокидывается вебпаком через localhost:{port} на сайт с плагином.
• dist/test/vsix // Нераспакованный vsix для dev.
• dist/prod/main.js // Собранным webpack.prod.js -webpack.dev.js // Файл конфигурации, который запускает webpack-devserver, следит за обновлениями в папке src и деплоит изменения в dist/test/deploy/
• webpack.prod.js
• vss-extension.json
• vss-extension.dev.json
• vss-extension.prod.json
• deployTest.ps1 // скрипт, который удаляет всё в папке dist/test/deploy, запускает webpack с конфигурацией webpack.dev.js (сохраняет в dist/test/deploy/dist скомпилированный main.js), затем создает расширение vsix в dist/test/vsix И распаковывает его в директорию dist/test/deploy. Делать это нужно лишь тогда, когда вы вносите изменения в index.html и в манифест расширения vss-extension.json, а также когда добавляете новый файлик в src. При других правках, например в index.tsx в директории src, все сделает webpack --hot после ctr+s.

Алгоритм:

1. Открываете корневую папку проекта, инициализируете каталог для гита и npm. И устанавливаете webpack, webpack-cli, webpack-dev-server и tfx, чтобы упаковывать расширение.
2. Правите под себя vss-extension.{ENV}.json, webpack.dev.js и webpack.prod.js, добавляете в webpack.dev.js url адрес вашего расширения на стенде, а также указываете любой baseUri, который вам нравится.
3. Запускаете скрипт test-deploy, либо сами делаете сборку webpack.dev.js, собираете вместе с ним vsix и распаковываете его в dist/test/deploy.
4. Устанавливаете vsix на стенд (если вы этого ещё не делали и если делали, но без baseUri).
5. Запускаете webpack-devserver с прокидыванием аргументов в команду путь на webpack.dev.js. Открываете свой любимый браузер, переходите по адресу https://localhost:{PORT}, соглашаетесь с рисками неподписанного сертификата. Теперь можете открывать сайт с вашим расширением. Нажимаете F12 и смотрите в каталог externalhost. Ваш исходный код располагается по адресу webpack:///./src.
6. Настраиваете свою IDE для дебага вашего сайта. Можете воспользоваться уже готовым таском Для vscode в папку .vscode/launch.json. У меня адекватно работает только с attach к firefox. Другие браузеры, если запускать их через vscode, не видят webpack:///, и поэтому не связывают ваш код в папке {WorkspaceFolder}\src с webpack:///./src. Сделав это, обновляете страницу плагина, чтобы vscode смог подцепить брекпойнты. Теперь можно вносить изменения в исходный код, сохранять их и эти изменения сразу применятся на сайте плагина. К сожалению, HMR настроить не смог :( Изменения он видит, обрабатывает, но применить не может, поэтому автоматом обновляет всю страницу.

Тоже самое, но коротко:

1. Установить на стенд TFS расширение с возможностью дебага (в конфигурации должен быть указан baseUri). В репозитории уже создан для этого скрипт test-deploy для npm, который можно выполнить командой npm run test-deploy или через PowerShell Core командой -NoProfile -ExecutionPolicy Unrestricted -File deployTest.ps1. Если выполнять скрипт через npm, необходимо проверить чтобы была указан переменная среды pwsh на PowerShell Core.
2. Выполнить команду npm run start и затем открыть хаб расширения на стенде TFS. Теперь TFS будет загружать файлы расширения из папки test\deploy и можно менять код расширения без повторной публикации расширения. HMR реализовать пока не получилось. Если вносить изменения в манифест vss-extension.{ENV}.json, то нужно обновлять расширение в менеджере расширений или маркет плейсе. Файлы расширения будут находиться в externalContentHot/webpack://./.

Важно! Чтобы дебажить в vscode, подключённым к firefox, нужно установить плагин Debugger for Firefox и настроить сам Firefox. Для настройки откройте firefox.exe через консольку с командой -start-debugger-server. Там нажимаете F12 и в настройках ставите галки в Advanced settings напротив Enable remote debugging и Enable browser chrome and add-on debugging toolboxes. Теперь можете открывать сайт плагина, и подключать vscode к firefox.