redb Route XML для VS Code: проекты из шаблонов, разметка, граф и диаграммы Mermaid

Расширение для VS Code в Marketplace: проект из шаблона, подсказки по схеме, ссылки на бины, дерево и граф маршрутов, Mermaid, путь до воркера Tsak.

Интеграционный маршрут в redb.Route можно написать на C#, а можно разметкой: файл .route.xml кладётся в пакет, пакет в папку воркера Tsak, и маршрут начинает работать. Формату редактор не нужен, это обычный XML, который сервис грузит как есть. Но писать его руками по памяти неудобно: какие у коннектора опции, как называется элемент, на какой бин сослаться, куда пойдёт сообщение, если ни одна ветка не подошла.

Для этого есть расширение redb Route XML для VS Code. С конца октября оно в Visual Studio Marketplace, текущая версия 0.2.25. Ниже весь путь с ним: от пустой папки и проекта из шаблона через разметку, подсказки и граф до диаграммы для документации и модуля на воркере.

Что это даёт

• Старт за минуту. Рабочий модуль с маршрутами, проверкой и стендом создаётся со страницы, без знания команд dotnet new и без поиска нужного пакета шаблонов.

• Ошибка видна, пока вы печатаете. Неверный элемент, опция не того коннектора или не той стороны эндпоинта подчёркиваются сразу, а не в логе воркера после выкладки.

• Опции коннекторов не нужно помнить. У одной Kafka больше сорока опций; редактор предлагает их с типами и допустимыми значениями, и это ровно то, что примет сервис текущего релиза.

• Маршрут понятен не только автору. Граф показывает границу транзакции, ветки и путь сообщения, которое не подошло ни под одно условие. С ним проще разбирать поток с аналитиком, тестировщиком или поддержкой, чем по тексту.

• Правки остаются аккуратными в git. Граф меняет только нужное место в тексте, поэтому изменение, сделанное мышью, на ревью выглядит как обычный короткий diff.

• Документация не расходится с кодом. Диаграмма Mermaid строится из того же маршрута, который работает на воркере, и обновляется одной командой.

• Ничего не стоит. Расширение распространяется под Apache 2.0, а схема, дерево и граф работают без сети.

Что умеет расширение

• New Project: страница, которая создаёт проект из шаблонов redb и сама ставит пакеты шаблонов.

• Схема: автодополнение элементов, атрибутов и опций каждого коннектора, проверка на лету.

• Заготовки: маршрут, выбор и блок обработки ошибок одной вставкой.

• Ссылки на бины: список объявленных объектов по #.

• Дерево маршрутов: все маршруты рабочей области с переходом на строку.

• Граф: маршрут как схема, которая правится мышью и остаётся текстом.

• Mermaid: диаграмма маршрута для README и вики.

Установка

В панели Extensions найдите redb Route XML и нажмите Install, или из терминала:

code --install-extension redb.redb-route-xml

Вместе с ним VS Code поставит Red Hat XML: подсказки и проверку по схеме выполняет он, а наше расширение отдаёт ему схему. Нужен VS Code 1.85 или новее.

Для машины без доступа к Marketplace, для VSCodium и Cursor тот же файл redb-route-xml-0.2.25.vsix приложен к релизам redb-route на GitHub: Extensions, меню ..., Install from VSIX. Без сети сначала так же ставится .vsix от Red Hat XML.

Новый проект без командной строки

Команда redb: New Project из палитры открывает страницу, которая создаёт проект из шаблонов redb через dotnet new. Вверху видно, что стоит на машине: SDK .NET и два пакета шаблонов, redb.Templates и redb.Tsak.Templates. Если пакета нет, рядом кнопка Install:

Когда на nuget.org выходит новая версия пакета, кнопка меняется на Update.

Каждый шаблон это карточка, и их здесь три группы.

Модули XML-маршрутов, двадцать шаблонов redb-route-*. Каждый создаёт модуль Tsak с маршрутами в разметке и тот же сценарий на C# рядом, в routes/*.cs: удобно сравнивать две записи одного потока. Среди них файлы (локальная папка, FTP, SFTP), REST API, SQL-outbox и пакетная вставка, объекты redb, Kafka, RabbitMQ, AMQP 1.0, MQTT, S3, LDAP, почта, AS2 и AS4, расписание Quartz, проверка XSD и XSLT, scatter-gather и набор шаблонов интеграции без брокера.

Хосты Tsak: воркер, который поднимает модули из своей папки, перезагружает их на лету, даёт API управления и планировщик.

Приложения на redb: консольное, сайты на Blazor и Razor Pages, Blazor WebAssembly с REST API на redb.Route, Blazor BFF, интеграционный воркер, приложение на redb.Identity, чат с LLM.

Справа форма с параметрами выбранного шаблона: имя проекта, целевая платформа, база данных, хранилище состояния, папка. Платформа, для которой на машине нет SDK, помечена, а папку, где уже лежат файлы, страница не примет.

Create запускает dotnet new, а если в проекте есть локальный манифест инструментов, ещё и dotnet tool restore. Вывод идёт на страницу и в канал redb Route, шаг можно отменить. В конце страница предлагает открыть проект в этом окне, в новом или добавить его в рабочую область.

Карточки и форма строятся из самих шаблонов. Новый шаблон в пакетах redb появляется на странице без обновления расширения.

Проект маршрутов

Дальше пример идёт на шаблоне redb.Route XML module: files (redb-route-file). Ему не нужен ни один сервер: папка входящих, проверка XSD, папки для обработанных и сбойных файлов, квитанция на каждый файл. Из терминала это та же команда, что запускает страница:

dotnet new install redb.Templates
dotnet new redb-route-file -n Orders

Orders/
  .config/dotnet-tools.json        локальный инструмент redb-route-xml
  context.xml                      документ контекста: бины, C#-маршруты
  routes/files.route.xml           два XML-маршрута
  routes/CsvFilesRoute.cs          тот же приём для CSV на C#
  resources/order.xsd              схема заказа
  config/orders.config.json        имя контекста и автозапуск, едет в пакете
  config/context.sample.json       образец настроек для выкладки
  deploy/docker-compose.files.yml  модуль на воркере Tsak

Раскладка проекта это соглашение формата. Маршруты лежат в routes/, ресурсы, на которые они ссылаются по имени, в resources/. context.xml грузится раньше маршрутов, поэтому маршруты видят его бины. В пакете едет только идентичность модуля, orders.config.json, а настройки приходят из конфигурации воркера: один и тот же пакет выкладывается на стенд и в прод без пересборки.

Разметка на примере

Вот второй маршрут из шаблона, тот, что обрабатывает входящие файлы:

<routes xmlns="urn:redb:route:1.0">
  <route id="orders-files-in" description="Processes the files of the inbox">
    <from uri="file://{{files.inbox:inbox}}?antInclude=*.xml&amp;delay=5000&amp;moveTo=done&amp;moveFailed=error"/>
    <convertBody type="System.String"/>
    <validateXsd file="resources/order.xsd" throwOnFailure="true"/>
    <log level="Information" showRouteId="true">
      <message>processed ${header.redbFile.NameOnly}: ${body}</message>
    </log>
    <setBody expr="received ${header.redbFile.NameOnly}"/>
    <to uri="file://{{files.outbox:outbox}}?fileName=${header.redbFile.NameOnly}.receipt"/>
  </route>
</routes>

Пять вещей, которых хватает, чтобы читать любой маршрут:

• <from> и <to> это вход и выход. URI устроен как в C#-маршрутах: схема коннектора, путь, опции. Длинный эндпоинт можно записать структурой, например <to><sql dataSource="#main-db"> с текстом запроса внутри.

• Шаги идут сверху вниз: привести тело к строке, проверить по XSD, записать в лог, подменить тело, отправить квитанцию. Если файл не прошёл схему, исключение уводит его в error/ по опции moveFailed.

• {{files.inbox:inbox}} это плейсхолдер настройки со значением по умолчанию. Он раскрывается из конфигурации воркера. Ключ без значения по умолчанию попадает в манифест пакета как обязательный.

• ${header...} и expr это язык выражений, тот же, что у C#-маршрутов. В условии строка становится предикатом, в значении вычисляется.

• Ветвления и обработка ошибок пишутся элементами: <choice> с <when expr="..."> и <otherwise>, <tryCatch> с <try>, <catch> и <finally>, <transaction> вокруг шагов, которые коммитятся вместе. Первый маршрут шаблона, генератор тестовых файлов, как раз использует <choice>: каждый пятый файл он нарочно делает не XML.

Загрузчик превращает разметку в те же вызовы DSL, что пишутся на C#, поэтому всё, что умеет движок, умеет и XML: ретраи, транзакции, историю сообщений, метрики, моки в тестах. Подробно формат, проверка пакета и замена модуля на лету разобраны в статье «XML-маршруты в redb.Route».

Подсказки по схеме

Документ начинается с пространства имён urn:redb:route:1.0. По нему Red Hat XML берёт схему, которую несёт расширение, и дальше работают автодополнение элементов и атрибутов, значения перечислений и проверка на лету. Привязка идёт по пространству имён, а не по имени файла: чужой route.xml без нашего пространства имён редактор не трогает.

Схема знает типизированные опции каждого коннектора. Наберите внутри маршрута <to><kafka и пробел, и редактор предложит topic, brokers, key, acks, compressionType и ещё несколько десятков опций Kafka с их типами и допустимыми значениями.

Схема различает стороны эндпоинта. Опция, которую принимает только отправитель, внутри <from> подчёркивается как ошибка: например, addressQuery у AS4 даст «The 'addressQuery' attribute is not allowed». Ошибка видна в редакторе, до сборки и до запуска.

В context.xml подсказки те же: внутри <context> после < редактор предлагает bean, components, dataFormat, deadLetterChannel, onInit, redb, routeBuilder, routeConfiguration.

Схему не пишут руками. Её генерирует инструмент redb-route-xml из сборок коннекторов при каждом релизе redb.Route, и релиз проверяет, что схема в расширении совпадает с его сборками. Новая опция коннектора приходит в редактор со следующей версией расширения.

Заготовки

Некоторые конструкции схема не подскажет целиком: маршрут без from или choice без веток бессмысленны. Для них есть три заготовки, которые вставляются там, где может начаться новый элемент:

Предлагаются они только в документах маршрутов redb и только на месте элемента: не внутри атрибута и не в чужом XML.

Ссылки на бины

Объекты реестра, фабрики подключений и обработчики, объявляются элементом <bean name="...">, а маршрут ссылается на них через #. Наберите #, и редактор покажет имена объявленных бинов. Подсказка работает в трёх местах: во всём значении атрибута (dataSource="#"), сразу после схемы URI (bean:#) и в значении опции URI (?headerFilterStrategy=#). Решётка внутри другого текста, например параметр SQL :#login, ссылкой не считается и подсказки не получает.

<routes xmlns="urn:redb:route:1.0">
  <bean name="main-db" type="redb.Route.Sql.Connection.SqlConnectionFactory, redb.Route.Sql">
    <constructorArg>
      <bean type="redb.Route.Sql.Connection.SqlConnectionOptions, redb.Route.Sql">
        <property key="ConnectionString" value="{{db.main.connection}}"/>
      </bean>
    </constructorArg>
  </bean>

  <route id="audit">
    <from uri="direct://audit"/>
    <to>
      <sql dataSource="#main-db">  <!-- здесь # предлагает main-db -->
        <![CDATA[ INSERT INTO audit_log(at) VALUES (CURRENT_TIMESTAMP) ]]>
      </sql>
    </to>
  </route>
</routes>

Граница подсказки в версии 0.2.25: она видит бины только текущего файла и не фильтрует их по типу. Шаблоны redb объявляют бины в context.xml, поэтому в файле маршрута из шаблона # пока ничего не предлагает. Неверную или висячую ссылку в любом случае ловят redb-route-xml check и pack: тип бина, его методы и свойства проверяются по настоящим сборкам.

Дерево маршрутов

Кнопка redb в панели действий открывает вид Routes: все документы маршрутов в рабочей области (*.route.xml, *.redb-route.xml), у каждого маршрута его id и эндпоинт from. Щелчок открывает файл на строке маршрута. Дерево обновляется само при создании, правке и удалении файлов и охватывает все папки рабочей области. Если маршрутов нет, вид предлагает создать проект.

На снимке маршрут запроса серийных номеров из демо SerialNumbers.Xml: проверка XSD в tryCatch, решение в транзакции, два выбора. Текстом он читается, но где граница транзакции и куда уходит сообщение без подходящей ветки, лучше видно в графе.

Граф маршрута

Кнопка графа в заголовке редактора, Open With и redb Route Graph или команда redb Route: Open Route Graph открывают тот же файл как граф. Граф это второй вид того же текста: каждая правка в нём становится правкой XML и отменяется обычным Ctrl+Z. Файл никогда не пересериализуется, каждая правка это точечная замена: комментарии, отступы и порядок атрибутов в нетронутом тексте остаются такими, какими их оставил автор, а новый атрибут из панели встаёт в конец тега. Шаг переезжает и удаляется вместе со строками комментария прямо над ним (пустая строка обрывает эту связь, комментарий под шагом остаётся на месте) и принимает отступ своего нового места. Текстовый редактор остаётся редактором по умолчанию.

Как читать граф:

• Плитки одного размера со значками в нотации Enterprise Integration Patterns и короткой подписью: from, bean, sql, choice, loop, log. Что делает шаг (имя свойства, условие, SQL), видно в подсказке и в панели свойств.

• Обёртки на линии маршрута. transaction, loop, split, metered ставят свои шаги между собственной плиткой и плиткой end; choice, tryCatch и filter расходятся ветками. Подряд идущие setHeader и setProperty сворачиваются в одну плитку set ×N.

• Пути по смыслу. Условные пути пунктиром: оранжевый там, где сообщение проходит мимо шага (фильтр не пройден, ни одна ветка не подошла, дубль), серый с крестом там, где оно отбрасывается (sample, debounce), красный там, где шаг бросает исключение. На снимке оранжевый путь «no match» обходит обе ветки choice внутри транзакции.

• Цвета по роли. Зелёный вход, синий выход, фиолетовый ваш код (bean), оранжевый изменение данных, бирюзовый маршрутизация, серый наблюдение, красный ошибки.

Что можно делать:

• Смотреть эндпоинт по полочкам. Для шага с URI панель свойств раскладывает его на схему, путь и опции коннектора, значения перечислений выбираются из списка. Чувствительная опция, пароль или ключ, замаскирована и из панели не правится.

• Видеть настройки. Значение {{files.inbox:inbox}} показано вместе с тем, во что оно раскроется: граф читает config/context.sample.json и config/*.config.json рядом с файлом или до трёх папок выше и складывает их так же, как воркер Tsak. Правка всегда сохраняет сам плейсхолдер.

• Править мышью. Шаг вставляется из палитры на любом «+» между шагами, удаляется клавишей Delete, перетаскивается на новое место или внутрь контейнера, переименовывается; атрибуты и тексты правятся в панели свойств.

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

Среди шаблонов самый наглядный граф даёт redb-route-eip: в его routes/orders.route.xml шесть шаблонов интеграции подряд.

Диаграммы Mermaid

Граф живёт в редакторе, а в README, вики или описание задачи нужна картинка, которая не разойдётся с кодом. Команда redb Route: Show Mermaid Diagram сохраняет текущий файл, запускает инструмент redb-route-xml mermaid и открывает текст диаграммы в новой вкладке Markdown. Для неё нужен инструмент .NET:

dotnet tool install -g redb.Route.Xml.CodeGen

В проекте из шаблона он уже есть в локальном манифесте, и та же диаграмма строится из терминала:

dotnet tool restore
dotnet redb-route-xml mermaid routes/files.route.xml

Вот что выходит для маршрутов шаблона redb-route-file, без правок:

Это текст, а не картинка: GitHub, GitLab и большинство вики рисуют такой блок сами, а в VS Code его видно через предпросмотр Markdown с расширением для Mermaid. Диаграмма строится из того же дерева определений, что и работающий маршрут: ромб choice, шестиугольник условия, овал otherwise, двойная рамка у эндпоинта отправки. Подписи узлов это имена шагов движка (setBodyExpression, richLogScope), а не элементов разметки, и длинные URI обрезаются.

Проверка и упаковка

Маршрут написан, граф проверен глазами. Дальше та же проверка, что и на сборочном сервере, только на вашей машине:

dotnet build -p:PackRouteOnBuild=true -p:Version=1.0.0

Сборка проверяет разметку по схеме, каждую опцию эндпоинта по её коннектору, бины по настоящим сборкам, ресурсы вроде resources/order.xsd и ключи конфигурации, затем пишет пакет pkg/orders-1.0.0.tpkg. Ошибка в разметке становится ошибкой сборки, пакет с ошибкой не собирается. Без пакета те же проверки запускает:

dotnet redb-route-xml check .

Что ещё она находит, например буквальные секреты в URI или висячие ссылки на бины, и как выглядят её сообщения, показано в статье про формат.

На воркер

Шаблон приносит и стенд: файл compose поднимает образ воркера Tsak и монтирует pkg/ как его папку модулей.

docker compose -f deploy/docker-compose.files.yml up -d

В логе пойдут строки processed order-N.xml: .... Каждый пятый тестовый файл нарочно не XML: он не проходит схему и уезжает в error/, остальные получают квитанцию в outbox. На своём воркере достаточно положить .tpkg в его папку modules: воркер поднимет модуль сам и так же выгрузит, если файл убрать. Настройки задаются в context.json рядом с пакетом или в конфигурации воркера. Как Tsak собирает сервисы из таких модулей, рассказано в статье про микросервисы на Tsak.

Границы

Версии

У расширения своя нумерация, 0.2.x, и она не движется вместе с пакетами redb. Схему, список элементов и каталог бинов каждый релиз redb.Route генерирует заново из своих сборок и сверяет с тем, что лежит в расширении. Расширение впервые вышло в Marketplace 23 октября 2026, версия 0.2.25 вышла 29 октября и соответствует релизу redb-route v4.6.0, тот же .vsix приложен и к нему. Расширение распространяется под лицензией Apache 2.0.