Pilot.ClientSdk - общий модуль для клиентских модулей Pilot
До версии 2.0.0 назывался Modules: сборка
113Modules.ext2, пространство имёнModules, пакетModules. Перевод модуля на новое имя:
- в
.csproj:Modules/<PackageReference Include="Pilot.ClientSdk" Version="2.0.0" />; вnuget.configфильтр источникаcicd-Pilot.*;- в коде:
using Modules…/using Pilot.ClientSdk….Модуль, собранный против
113Modules.ext2, с 2.0.0 не загрузится: его нужно пересобрать. На серверах объект модуля тот же - веб-админка обновила его по прежнему имени (AssemblyMetadata("PreviousNames")).
Общие данные
- Постановщик задания на создание: -
- Отделы, использующие модуль: разработчики клиентских модулей Pilot
- Задача в Битриксе и/или в Инфраменеджере: -
- Не явно связанные модули:
111NugetPackage.ext2(прежний общий модуль - Pilot.ClientSdk его не заменяет автоматически, см. раздел 5),112Reports.ext2(то же для отчётов) - Веб-админка:
proadmin, вкладка «Модули» (CI/CD модулей: тест / стейдж / прод) - Сервис статистики:
stack/metrics/report-collector(POST /api/module-events), дашборд Grafana «Pilot - клиентские модули» - Имя общих настроек: «Модули общие настройки» (ключ
Pilot.ClientSdk-6C1F2E7A-3B54-4D8E-9A0B-71E5C2D4F813), см. 2.3; значения по умолчанию -Pilot.ClientSdk.config.jsonрядом с dll - Путь к файлу логирования:
%AppData%\ASCON\Units Logs\Logs\Pilot.ClientSdk.log
Краткое описание
Клиентский модуль Pilot 113Pilot.ClientSdk.ext2 (net48, пространство имён Pilot.ClientSdk). Его подключают другие клиентские модули. Он делает три вещи:
- Статистика модулей в Grafana.
ModuleStatsсчитает, какие действия модулей вызывают, сколько из них успешны, сколько длятся и с какой ошибкой падают. Отдельно модуль сообщает, какие модули и в каких версиях загружены у пользователя. Так после выкладки из админки видно, дошла ли новая версия до рабочих мест. - Проверка загрузки модулей. При старте клиента поверх главного окна Pilot открывается окно «Загрузка модулей»: все ли назначенные пользователю модули скачались, загрузились и запустились и сколько занял запуск. Пока проверка идёт, окно нельзя закрыть (до 15 с).
- Общие методы SDK. Загрузка объектов, поиск, атрибуты, навигация по дереву, оргструктура, изменение данных, нумераторы, лог, команды MVVM. Это переработанные популярные методы из
NugetPackage: без NLog и System.Reactive (в общем AppDomain клиента их версии у разных модулей конфликтуют) и без известных ошибок старых загрузчиков.
Модуль (ModuleStats.Run …) ──Pilot.ClientSdk (клиент Pilot) ──пачка раз в 15 с──report-metrics-collector (:5310)
│
PostgreSQL pilot_metrics.metrics.module_events ──Grafana «Pilot - клиентские модули»
Содержание
- Быстрый старт
- Статистика модуля (ModuleStats)
- Общие методы
- Сборка, выпуск, CI/CD
- Переход с NugetPackage
- Как это устроено внутри
- Типовые проблемы
1. Быстрый старт
Подключение - NuGet-пакет Pilot.ClientSdk из реестра пакетов GitLab (подробно - 4.1; первый раз на машине - подключить источник GitLab и войти, 4.2). Сборка в пакете лежит в ref/net48: она нужна только для компиляции и в bin и zip модуля не копируется. В клиенте её уже загрузил модуль 113Pilot.ClientSdk.ext2, вторая копия дала бы конфликт типов.
nuget.config рядом с .csproj модуля (образец - в Test-module; адрес GitLab gitlab.example.local и PROJECT_ID замените на свои, см. 4.1):
<configuration>
<packageSources>
<clear />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
<add key="cicd" value="http://gitlab.example.local/api/v4/projects/PROJECT_ID/packages/nuget/index.json" allowInsecureConnections="true" />
</packageSources>
<packageSourceMapping>
<packageSource key="nuget.org"><package pattern="*" /></packageSource>
<packageSource key="cicd"><package pattern="Pilot.*" /></packageSource>
</packageSourceMapping>
</configuration>
.csproj модуля:
<PackageReference Include="Pilot.ClientSdk" Version="2.1.1" />
Копию dll в папке lib/ модуля больше не храните.
Минимальный модуль:
using Ascon.Pilot.SDK;
using Ascon.Pilot.SDK.Menu;
using Pilot.ClientSdk;
using Pilot.ClientSdk.Telemetry;
[Export(typeof(IMenu<ObjectsViewContext>))]
public class StartPoint : IMenu<ObjectsViewContext>, IModule // IModule - обязательно, см. раздел 2а
{
private static readonly ModuleStats Stats = ModuleStats.For<StartPoint>(); // модуль и версия - из сборки
private static readonly ModuleLogger Log = new ModuleLogger("OpenStoradge");
private readonly IObjectsRepository _repository;
private Loader _loader;
[ImportingConstructor]
public StartPoint(IObjectsRepository repository, ISearchService search, IObjectModifier modifier)
{
PilotApi.Init(repository, search, modifier); // если модуль стартует раньше Pilot.ClientSdk - не помешает
_repository = repository;
StartupRunner.Run(this); // последней строкой: замер запуска для окна загрузки
}
public void Initialize() => _loader = new Loader(_repository);
public void Build(IMenuBuilder builder, ObjectsViewContext context) =>
builder.AddItem("OpenStoradge", 0).WithHeader("Открыть Storadge");
public async void OnMenuItemClick(string name, ObjectsViewContext context)
{
if (name != "OpenStoradge")
return;
try
{
await Stats.RunAsync("Открыть Storadge", async op =>
{
var obj = context.SelectedObjects.First();
var project = await _loader.ProjectAsync(obj); // папка 0_project выше по дереву
var docs = await PilotApi.Searcher.ByTypeAsync("pir_doc", inContext: project?.Id);
op.Items = docs.Count; // сколько обработано - в Grafana
Open(project.Str("storadge_path"), docs);
});
}
catch (Exception ex)
{
Log.Error("Открыть Storadge", ex); // ошибка уже в статистике, здесь - в лог
PilotApi.Dialogs?.ShowError(ex.Message, "Открыть Storadge"); // (текст ошибки, заголовок)
}
}
}
Модуль с
using Pilot.ClientSdkработает, только если113Pilot.ClientSdk.ext2назначен пользователю на сервере. Без него клиент не загрузит типы модуля. Назначьте Pilot.ClientSdk всем пользователям раньше модулей, которые на нём построены.
2. Статистика модуля (ModuleStats)
2.1. API
| Член | Что делает |
|---|---|
ModuleStats.For<T>(), ModuleStats.For(assembly), ModuleStats.Current |
статистика модуля, которому принадлежит сборка. Имя = имя сборки (087OpenStoradge.ext2), название = AssemblyProduct (как в Pilot-myAdmin), версия = AssemblyVersion |
Run("Действие", () => …) / Run("Действие", op => …) / Run<T>(…) |
выполнить и записать: длительность, успех, ошибку (исключение пробрасывается дальше), отмену (OperationCanceledException) |
RunAsync(…) |
то же для async-кода |
Start("Действие") |
замер через using: op.Fail(ex), op.Cancel(), op.Items = n; без них - успех |
Use("Действие", items) |
факт использования без длительности (открыли окно, нажали кнопку) |
Error("Действие", ex), Cancelled("Действие") |
записать ошибку или отмену, пойманную модулем самим |
Название действия - то, что увидит аналитик в Grafana. Пишите его по-русски, как пункт меню: «Создание бланков», «Выгрузка в Storadge». Не вставляйте в название Id объектов и имена файлов, иначе одно действие распадётся на тысячи строк.
2.2. Что отправляется
| Поле | Откуда |
|---|---|
kind |
action - действие, load - модуль загружен клиентом (его отправляет сам Pilot.ClientSdk через минуту после старта клиента, для каждого загруженного модуля) |
module, module_title, module_version |
атрибуты сборки модуля |
action, status (success / error / cancelled), duration_ms, items |
из Run / Start / Use |
error_type, error_message |
тип и текст исключения (корневого), текст обрезается до 2000 символов |
login, person, server, client_type, client_version, machine, lib_version |
текущий пользователь, адрес сервера Pilot (по нему сервис определяет контур prod/test/stage), клиент, компьютер, версия Pilot.ClientSdk |
Данные объектов, параметры и содержимое документов не отправляются. Но login, person (ФИО), machine (имя компьютера) и server (адрес подключения клиента к серверу Pilot) - персональные сведения, а в тексте ошибки могут оказаться пути и имена из сообщения исключения. Отправка идёт обычным HTTP без шифрования (ключ apiKey - в заголовке X-Api-Key): направляйте её только на сервис внутри доверенной сети или задайте https://-адрес. Если такие сведения отправлять нельзя - statsEnabled: false.
2.3. Отправка и настройка
События копятся в памяти и уходят пачкой раз в flushSeconds секунд. Если набралось 100 событий, пачка уходит сразу. Событие со статусом error тоже отправляется сразу, не дожидаясь периода, чтобы ошибка не потерялась при закрытии клиента. Оставшееся отправляется и при закрытии клиента (ждём не больше 3 с). На диск события не пишутся. Если сервис недоступен, пачка пишется в лог и теряется, остаток очереди ждёт следующего тика. Очередь ограничена 5000 событиями. События, которые модуль прислал до старта Pilot.ClientSdk, тоже ждут в очереди.
Настройки задаются в двух местах (по убыванию приоритета):
- Общие настройки Pilot / «Модули общие настройки». Их задаёт администратор: Pilot / Сервис / Настройки / Общие настройки. Значения действуют на всех пользователей и важнее файла. Клиенты получают их при запуске и при каждом изменении, без перезапуска. Статистика, трей и список исключений применяются сразу, режим окна загрузки - при следующем запуске клиента. Кнопка «Проверить» у адреса делает
GET <сервер>/healthсервиса статистики с компьютера администратора. Кнопка «Очистить раздел» возвращает настройки из файла. Pilot.ClientSdk.config.jsonлежит рядом с dll и входит в zip модуля. Его значения действуют, пока раздел общих настроек пуст. Редактор раздела при первом открытии показывает именно их.
Формат одинаковый: раздел общих настроек хранит тот же JSON.
{
"statsEnabled": true,
"statsUrl": "http://<docker-хост>:5310/api/module-events",
"apiKey": "",
"flushSeconds": 15,
"reportLoadedModules": true,
"startupWindowMode": "always",
"startupLockSeconds": 15,
"startupAutoClose": true,
"ignoredModules": [],
"trayMenu": true
}
| Поле | В редакторе | Назначение |
|---|---|---|
statsEnabled |
Отправлять статистику | false - статистика не собирается |
statsUrl |
Адрес сервиса статистики | адрес сервиса сбора, доступный с рабочих мест. В поставляемом Pilot.ClientSdk.config.json стоит http://localhost:5310/...: он годится только на машине, где запущен сервис; на рабочих местах задайте адрес в общих настройках |
apiKey |
API-ключ | если в сервисе задан COLLECTOR_API_KEY - тот же ключ |
flushSeconds |
Интервал отправки | как часто отправлять пачку, 1-3600 с |
reportLoadedModules |
Отправлять список модулей | отправлять список загруженных модулей (модуль = сборка *.ext2 с AssemblyCompany("CICD")) |
startupWindowMode |
Окно «Загрузка модулей» | always - при каждом запуске; problems - только если модуль не скачан, не загрузился или упал при запуске; never - не показывать, проверка пишется только в лог и Grafana. Старый флаг "startupWindow": false равен never |
startupLockSeconds |
Сколько ждать загрузки | сколько секунд окно нельзя закрыть, пока модули грузятся, и сколько их ждать (потом незагрузившийся модуль - ошибка), 0-600 с |
startupAutoClose |
Закрывать окно само | закрыть окно само, если все модули запустились без ошибок |
ignoredModules |
Не проверять модули | части названий модулей или имён сборок, которые не показываются в окне загрузки и не считаются ошибкой (например, сторонние модули) |
trayMenu |
Пункты в трее | показывать пункты «Модули версии / загрузка» в меню трея |
На машине разработчика адрес можно переопределить переменной окружения CLIENTSDK_STATS_URL.
2.4. Где смотреть
Grafana / папка «CI/CD Pilot» / дашборд «Pilot - клиентские модули» (stack/metrics/report-collector/grafana/dashboard-pilot-modules.json): плитки, сводка по модулям, графики по статусам и модулям, действия внутри модулей, версии модулей на рабочих местах, пользователи, самые долгие действия, последние ошибки.
В клиенте Pilot: трей / «Модули версии» - какие модули загружены, куда уходит статистика и откуда взяты настройки; «Модули загрузка» - окно проверки загрузки модулей.
2а. Стартовый класс (IModule) и окно загрузки модулей
Регламент: стартовый класс модуля
В каждом модуле стартовый класс реализует IModule (или IModuleAsync) и последней строкой [ImportingConstructor] вызывает StartupRunner.Run(this) (StartupRunner.RunAsync(this)). Стартовый класс - тот, который клиент создаёт при старте: обычно IDataPlugin StartPoint, а если IDataPlugin нет - главный экспорт модуля (например, IMenu<…>). В конструкторе остаётся только сохранение сервисов SDK, вся остальная инициализация переезжает в Initialize().
[Export(typeof(IDataPlugin))]
public sealed class StartPoint : IDataPlugin, IModule
{
private readonly IObjectsRepository _repository;
private readonly IObjectModifier _modifier;
[ImportingConstructor]
public StartPoint(IObjectsRepository repository, IObjectModifier modifier)
{
_repository = repository;
_modifier = modifier;
StartupRunner.Run(this); // замер: время, успех, ошибка
}
public void Initialize()
{
Instance = this;
// подписки, загрузка настроек, регистрация обработчиков …
}
}
// Асинхронная инициализация (загрузка объектов, поиск, сеть):
public sealed class StartPoint : IDataPlugin, IModuleAsync
{
[ImportingConstructor]
public StartPoint(IObjectsRepository repository)
{
_repository = repository;
StartupRunner.RunAsync(this); // без await: задача никогда не падает; пока она идёт, модуль «запускается…»
}
public async Task InitializeAsync() => _settings = await LoadSettingsAsync();
}
| Что | Как |
|---|---|
Исключение из Initialize / InitializeAsync |
не пробрасывается: клиент не падает, остальные части модуля работают. Ошибка попадает в окно загрузки («ошибка запуска» и текст), в Pilot.ClientSdk.log и в Grafana действием «Запуск модуля» со статусом error |
| Время | от StartupRunner.Run до конца Initialize (для async - до завершения задачи). Видно в окне и в Grafana (duration_ms действия «Запуск модуля») |
| Несколько стартовых классов в модуле | Run можно вызвать в каждом: в окне время суммируется, ошибка любого класса - ошибка модуля |
| Пример | Test-module/Pilot/StartPoint.cs |
Модулю, собранному с IModule, нужен Pilot.ClientSdk с этим интерфейсом на сервере. Сначала выложите Pilot.ClientSdk, потом модули, иначе клиент не загрузит модуль (TypeLoadException).
Окно «Загрузка модулей»
Pilot.ClientSdk открывает его, когда появляется главное окно Pilot. Окно модальное: пока оно открыто, работать с Pilot нельзя. Закрыть его можно, когда проверены все модули или прошло startupLockSeconds (15 с), на кнопке идёт обратный отсчёт. Если всё запустилось без ошибок, окно закрывается само (startupAutoClose). Открыть повторно: трей / «Модули загрузка». Кнопка «Скопировать отчёт» кладёт таблицу в буфер обмена, её можно приложить к заявке в поддержку.
Как проверяется каждый модуль:
| Шаг | Откуда берётся | Статус в окне |
|---|---|---|
| 1. Назначен пользователю | объекты Extension в папке расширений сервера (SystemObjectIds.ExtensionRootObjectId и подпапки), которые видит пользователь, не в корзине |
- |
| 2. Скачан | клиент распаковывает zip модуля в %LocalAppData%\ASCON\<клиент>\Databases\<база>\<версия>\Plugins\<Body.Id файла>: есть ли эта папка |
не скачан (ошибка) |
| 3. Загружен | сборка *.ext2 из этой папки (или с тем же именем) есть в AppDomain клиента |
загрузка… / не загружен (ошибка, через 15 с) |
| 4. Запущен | сторонний модуль (без AssemblyCompany("CICD")) дальше не проверяется |
загружен |
модуль без IModule |
загружен, без IModule (замечание) | |
модуль с IModule - по отчёту StartupRunner |
ожидание запуска… / запускается… / запущен / ошибка запуска; нет отчёта за 15 с - «нет отчёта о запуске» (замечание) |
Модули, загруженные не с сервера (папка Development), показываются отдельными строками с пометкой «(локально)». Если список с сервера получить не удалось (нет связи или прав на папку расширений), окно проверяет только загруженные модули и пишет об этом под заголовком.
Итог проверки пишется в Pilot.ClientSdk.log (каждая проблема отдельной строкой) и уходит в Grafana действием «Проверка загрузки модулей» модуля Pilot.ClientSdk: items - сколько модулей проверено; при ошибках статус error, а в error_message - список модулей (тип ModulesNotLoadedException).
Администратор с правами на всю папку расширений видит и модули, которые ему лично не назначены. У него такие модули будут «не скачан». У обычных пользователей список совпадает с назначенными модулями.
3. Общие методы
Пространство имён Pilot.ClientSdk. Все методы чтения безопасны к null: если объекта, атрибута или значения нет, вернётся ""/null/пустой список, исключения не будет.
Что было в NugetPackage / что использовать
| NugetPackage | Pilot.ClientSdk | Что исправлено |
|---|---|---|
ObjectLoader, ObjectLoaderSync, IdLoader |
Loader.LoadAsync(id / ids), Load(…) (синхронно), WaitAsync(id, условие) |
один экземпляр можно вызывать параллельно. Несуществующие объекты и объекты без прав не подвешивают загрузку. Таймаут возвращает уже загруженное. Порядок результата = порядок Id |
SearchHelper, Searcher |
Search.IdsAsync / ObjectsAsync(b => …), ByTypeAsync, ByTypesAsync, ByAttributeAsync, ByOrgUnitAsync |
ждёт полный (Remote) результат с таймаутом. По умолчанию ищет живые и замороженные объекты. Тип можно задать по имени |
GetStringAttribute, GetAttribute<T> |
obj.Str, StrOrNull, Attr<T>, Date, DateStr, Int, Double, GuidAttr, OrgUnitIds, Has |
числа приводятся между int/long/double. Даты - в локальном времени |
GetParentByType, GetProjectFolder, GetAllChildren |
Loader.ParentOfTypeAsync, SelfOrParentOfTypeAsync, ProjectAsync, AncestorsAsync, ChildrenAsync(obj, типы…), RelatedAsync |
не падает на корне и не уходит в бесконечную рекурсию. Дети грузятся одним запросом |
CreateObject, AddFileByPath, CreateRelation |
modifier.CreateChild(parent, "тип", атрибуты), SetAttributes, SetAttributeValue, AddFileObject, Link |
Apply() вызывает модуль (одна транзакция). Нет Task.Delay «на удачу» - после Apply используйте Loader.WaitAsync |
OrganisationUnitService, OrganisationUnitWrapper |
Org: Parent, Ancestors, DepartmentOf, PositionIds, PersonIdsIn, UnitByTitle, ContrAgent, Path |
префиксы контрагентов настраиваются, дерево без циклов |
TypeExtensions |
ConstAttrValue, AttributeTitle, IsTaskType, IsWorkflowType, IsWorkflowStageType |
битая конфигурация атрибута / "" вместо исключения |
PilotNumeratorService |
NumeratorService: GetNumeratorValue, SetNumeratorAttribute, WaitNumberAsync |
ожидание номера - через подписку, без опроса раз в 300 мс |
ModuleLogger (NLog) |
ModuleLogger (без NLog) |
тот же путь %AppData%\ASCON\Units Logs\Logs\{имя}.log |
RelayCommand |
RelayCommand, AsyncRelayCommand |
асинхронная команда блокирует повторный запуск и не роняет клиент исключением |
IconLoader |
EmbeddedResources.GetBytes(путь, сборка) |
|
DValueExtensions.ToInt/ToBool |
Text.ToInt/ToBool |
|
| - | Text.Fio, ShortName, CleanTitle, JoinNonEmpty, CompareCodes, CodeComparer |
как в Reports |
Темы Jedi/Sith, стили кнопок и ByteImageConverter (SVG через SharpVectors) остались в NugetPackage: это WPF-ресурсы со сторонней зависимостью, к общим методам они не относятся. (В самом Pilot.ClientSdk SharpVectors подключена в .csproj, но не используется.)
Pilot - сервисы SDK в одном месте
| Член | Описание |
|---|---|
Repository, Search, Modifier, Files, Dialogs, Tabs, ClientInfo, PersonalSettings, AttributeFormatParser |
заполняются при старте Pilot.ClientSdk. PilotApi.Init(...) модуля не затирает уже сохранённые сервисы |
IsReady, CurrentPerson, Type(name), TypeId(name) |
|
LoadAsync, Load, SearchIdsAsync, SearchObjectsAsync |
короткие вызовы Loader / Searcher |
Loader, Searcher, Org |
Loader, Search, Org на сервисах Pilot |
Примеры
// Загрузка и атрибуты
var doc = await PilotApi.LoadAsync(id);
var code = doc.Str("code");
var deadline = doc.DateStr("deadlineDate");
if (doc.Is("pir_doc") && doc.IsAlive()) { … }
// Поиск: документы типа в папке проекта с атрибутом
var docs = await PilotApi.Searcher.ByAttributeAsync("pir_doc", "stage", "РД", inContext: project.Id);
// Любые условия
var tasks = await PilotApi.SearchObjectsAsync(b =>
{
b.Must(ObjectFields.TypeId.Be(PilotApi.TypeId("task_approval")));
b.Must(AttributeFields.OrgUnit("executor").BeAnyOf(PilotApi.Org.PositionIds(dept.Id).ToArray()));
});
// Создание и ожидание результата после Apply
var builder = PilotApi.Modifier.CreateChild(folder, "archive_blank", new Dictionary<string, object> { ["name"] = "Бланк" });
new NumeratorService(PilotApi.AttributeFormatParser).SetNumeratorAttribute(builder, PilotApi.Type("archive_blank"), "number");
PilotApi.Modifier.Apply();
var created = await new NumeratorService(PilotApi.AttributeFormatParser).WaitNumberAsync(PilotApi.Repository, builder.DataObject.Id, "number");
// Оргструктура
var org = PilotApi.Org;
var dept = org.DepartmentOf(PilotApi.CurrentPerson);
var people = org.PersonIdsIn(dept.Id);
Load* и Search* можно вызывать с UI-потока (через await интерфейс не блокируется) и из фонового потока. Подписки SDK модуль сам создаёт на UI-потоке. Синхронный Load(...) на UI-потоке ждёт во вложенном цикле сообщений, окно не замирает.
4. Сборка, выпуск, CI/CD
Требования: .NET SDK 8+ (собирает net48; в CI - SDK 10.0.404), Windows для отладки в клиенте.
dotnet build -c Debug # + копия в %LocalAppData%\ASCON\Pilot-BIM\Development\113Pilot.ClientSdk.ext2
dotnet build -c Release # bin\113Pilot.ClientSdk.ext2-<версия>.zip - для загрузки на сервер
dotnet test tests/Pilot.ClientSdk.Tests
dotnet pack -c Release -o out # NuGet-пакет Pilot.ClientSdk (ref/net48) - в реестр его публикует CI (задания nuget_*)
- Отладка. Debug-сборка кладёт модуль в папку разработки Pilot-BIM. Клиент подхватывает его при запуске.
-p:CopyToPilot=false- не копировать. - Выпуск - через CI/CD модулей (
.gitlab-ci.ymlпо шаблонуclient-modules/ci-template, вкладка «Модули» в веб-админке, см. README модулей). Версию, CHANGELOG и теги ставит админка. Руками вVersionничего поднимать не нужно. - NuGet-пакет - свой CI (jobs
nuget_*в.gitlab-ci.yml), см. 4.1. - Тесты: запуск
IModule/IModuleAsync(успех; ошибка не пробрасывается), статусы окна загрузки (не скачан, не загружен, сторонний, без интерфейса, без отчёта, запускается, ошибка, локальные модули), настройки окна; JSON событий, атрибуты сборки, конфиг,Run/RunAsync(успех, ошибка, отмена), очередь до старта, выключенная статистика, недоступный сервис (остаток очереди не теряется), подписки SDK (результат, таймаут с неполным результатом, ошибка, отмена, синхронное ожидание), ФИО, шифры, оргструктура. Интеграционный тест с настоящим сервисом запускается, если заданCLIENTSDK_IT_URL(напримерhttp://localhost:5310/api/module-events); без неё xUnit показывает его как пропущенный, а не пройденный. - Тесты в CI. Проект тестов - net48 и WPF, на Linux-раннере он не запускается: задание
build_testsпроверяет, что он собирается. Запуск - заданиеtestна Windows-раннере с тегомwindows. Переменная CI/CDWINDOWS_RUNNER=trueвключает его в каждом pipeline; без неё задание ручное и pipeline на него не ждёт.
4.1. NuGet-пакет
Пакет Pilot.ClientSdk публикуется в реестр пакетов этого проекта GitLab (Deploy / Package registry) заданиями nuget_* из .gitlab-ci.yml: dotnet pack и dotnet nuget push с токеном CI_JOB_TOKEN, отдельный ключ не нужен. Числовой id проекта (PROJECT_ID в адресе источника) - Settings / General / Project ID. Номер пакета берётся из <Version> в .csproj, суффикс дописывает CI:
| Ветка | Пакет | Для чего |
|---|---|---|
| merge request | собирается, не публикуется (nuget_check) |
пакет собирается |
dev |
X.Y.Z-dev.<номер pipeline> (nuget_dev) |
модули на тестовом сервере проверяются с новым Pilot.ClientSdk |
release/X.Y.Z |
X.Y.Z-rc.<номер pipeline> (nuget_rc; пока версия в csproj не равна X.Y.Z, не публикуется) |
стейдж |
main |
X.Y.Z (nuget_release, после выкладки в прод deploy_prod) |
прод: на эту версию ссылаются модули |
«Номер pipeline» - CI_PIPELINE_IID, порядковый номер pipeline внутри проекта. Тег vX.Y.Z и GitLab Release ставит веб-админка при выпуске в прод. Опубликованную версию пакета GitLab перезаписать не даёт: при повторе nuget_release дубликат может быть отклонён.
Модули ссылаются на версию из main. Предварительную версию (-dev.N, -rc.N) берите только на время проверки и до выпуска в прод верните стабильную. Иначе модуль в проде будет собран против Pilot.ClientSdk, которого в проде ещё нет.
Доступ к пакету:
- CI модуля. Job
build_moduleшаблонаci-templateнаходит вnuget.configисточники с/api/v4/и входит в них токеном job (gitlab-ci-token/CI_JOB_TOKEN). Если restore в job получает 403/404, в проекте Pilot.ClientSdk откройте Settings / CI/CD / Job token permissions и добавьте в разрешённые группуclient-modules. - Своя машина. Один раз подключите источник GitLab и войдите в него. Пошагово - в 4.2.
4.2. Источник GitLab на своей машине
Пакет лежит в GitLab, а не на nuget.org, поэтому Visual Studio (или dotnet) должна знать адрес источника и входить в него под вами. Это делается один раз на машине и действует для всех модулей.
Адрес источника (подставьте адрес вашего GitLab и id проекта Pilot.ClientSdk):
http://gitlab.example.local/api/v4/projects/PROJECT_ID/packages/nuget/index.json
Шаг 1. Личный токен GitLab
Реестр пакетов GitLab принимает только токен, обычный пароль от GitLab не подходит.
- GitLab / аватар справа вверху / Edit profile / Access tokens / Add new token.
- Имя - например
nuget, срок - на ваше усмотрение, права (scopes) -read_api. - Create personal access token и сразу скопируйте токен: GitLab показывает его один раз.
Шаг 2. Источник в Visual Studio
Если в репозитории модуля есть nuget.config с источником cicd (как в Test-module), Visual Studio подключит источник сама при открытии решения. Переходите к шагу 3.
Если nuget.config нет (новый модуль) - добавьте источник вручную или лучше скопируйте nuget.config из Test-module. Вручную:
- Сервис / Параметры / Диспетчер пакетов NuGet / Источники пакетов (Tools / Options / NuGet Package Manager / Package Sources).
- Кнопка «+». Внизу: Имя -
cicd, Источник - адрес выше. Обновить / ОК.
Источник по http://, поэтому Visual Studio предупредит о небезопасном подключении (NU1803). Внутри сети это нормально. В новых версиях Visual Studio и .NET SDK 9+ это ошибка NU1302. Её снимает только allowInsecureConnections="true" у источника в nuget.config, поэтому лучше подключать источник через nuget.config, а не через окно параметров.
Шаг 3. Вход: окно логина и пароля
При первом восстановлении пакетов Visual Studio покажет окно входа в источник. Это бывает при сборке, при открытии решения или в Управление пакетами NuGet с выбранным источником cicd. Окно называется «Учётные данные Windows» или «Требуется проверка подлинности», в нём адрес вашего GitLab:
| Поле | Что вводить |
|---|---|
| Имя пользователя | ваш логин GitLab (не почта) |
| Пароль | личный токен из шага 1, не пароль от GitLab |
Поставьте «Запомнить учётные данные»: Visual Studio сохранит их в диспетчере учётных данных Windows, и окно больше не появится.
Если ввели неправильно и окно больше не появляется, а restore пишет 401:
- Панель управления / Диспетчер учётных данных / Учётные данные Windows.
- Удалите запись с адресом вашего GitLab (обычно начинается с
VSCredentials_). - Перезапустите Visual Studio, окно входа появится снова.
Вариант без Visual Studio: командная строка (Rider, dotnet build)
dotnet окна входа не показывает, логин и токен записываются в пользовательский NuGet.Config. На Windows токен шифруется средствами DPAPI, в репозиторий он не попадает:
dotnet nuget add source http://gitlab.example.local/api/v4/projects/PROJECT_ID/packages/nuget/index.json -n cicd -u <логин GitLab> -p <токен> --configfile %AppData%\NuGet\NuGet.Config
Токен сменился - та же команда с update вместо add (без адреса):
dotnet nuget update source cicd -u <логин GitLab> -p <новый токен> --configfile %AppData%\NuGet\NuGet.Config
Проверка и типовые ошибки
В папке модуля: dotnet restore. Должно быть Restored …, в «Зависимости / Пакеты» проекта появится Pilot.ClientSdk.
| Ошибка | Причина | Что делать |
|---|---|---|
401 Unauthorized |
неверный логин или вместо токена введён пароль | шаг 3: удалить сохранённые учётные данные и войти логином и токеном |
NU1101 … No packages exist with this id in source(s): cicd |
у токена нет read_api или у вас нет доступа к проекту client-modules/pilot-clientsdk |
новый токен с read_api; доступ к проекту - у владельца группы client-modules |
503 или таймаут |
в системе задан прокси (HTTP_PROXY), запрос ушёл через него |
добавить адрес GitLab в NO_PROXY (переменные среды Windows) и перезапустить Visual Studio |
NU1302 / NU1803 (HTTP) |
источник по http:// |
источник из nuget.config с allowInsecureConnections="true" |
NU1101 в CI GitLab |
job модуля не допущен к пакетам Pilot.ClientSdk | в проекте Pilot.ClientSdk: Settings / CI/CD / Job token permissions / группа client-modules |
Структура
Pilot.ClientSdk.csproj, AssemblyInfo.cs, Pilot.ClientSdk.config.json, .gitlab-ci.yml
Pilot/ ModuleStartup (IDataPlugin - точка входа), TrayMenu («Модули версии» / «- загрузка»), CommonSettings и SettingsEditor (общие настройки)
Startup/ IModule, StartupRunner (API для модулей), ModuleCheck (статусы), ModuleSources (сервер, Plugins, AppDomain),
StartupMonitor (когда показать окно, итог в лог и Grafana), StartupWindow
Telemetry/ ModuleStats (API), ModuleEvent (JSON), StatsSender (очередь и отправка), ModuleIdentity, ClientEnvironment
Common/ PilotApi, Loader, Search, DataObjectExtensions, Modify, Org, TypeExtensions,
NumeratorService, Text, ModuleLogger, RelayCommand, EmbeddedResources
Infrastructure/ ModuleConfig, ModuleLog, Json, SdkSubscription (IObservable SDK / Task)
tests/ Pilot.ClientSdk.Tests (xUnit, net48)
5. Переход с NugetPackage
- NugetPackage не удаляется: модули на нём продолжают работать. Переводите модуль на Pilot.ClientSdk, когда в нём и так идёт задача.
- Оба модуля можно подключить одновременно. Пространства имён разные (
Pilot.ClientSdkиClientModules/NugetPackage), но именаModuleLoggerиRelayCommandсовпадают. Если в файле есть обаusing, уточните тип. - Статистику можно добавить в модуль на NugetPackage - достаточно подключить Pilot.ClientSdk и обернуть действия в
Stats.Run(...).
6. Как это устроено внутри
- Загрузка.
ModuleStartupэкспортируется какIDataPluginи сам реализуетIModule. Клиент создаёт его при старте и передаёт в конструктор сервисы SDK. Они сохраняются вPilot, запускаются отправка статистики и проверка загрузки модулей. - Окно загрузки.
StartupMonitorсразу запрашивает список модулей с сервера и раз в 300 мс (до 3 минут) проверяетApplication.Current.MainWindow. Когда главное окно видно, открывает окно проверки черезShowDialog(в режимеproblemsсначала молча ждёт итога и открывает окно, только если есть ошибки). Окно пересчитывает статусы раз в 400 мс. ОтчётыStartupRunnerкопятся в статическом списке, поэтому не важно, создаст клиент модуль раньше Pilot.ClientSdk или позже. - Общие настройки.
CommonSettingsэкспортируется какISettingsFeature2: раздел «Модули общие настройки» и редакторSettingsEditor, собранный в коде без XAML. Значение раздела - JSONModuleConfig.ModuleStartupподписывается на него черезIPersonalSettings.SubscribeSetting, и каждое значение попадает вModuleConfig.ApplyCommon. СобытиеModuleConfig.ChangedперенастраиваетStatsSender: новый адрес, ключ и период действуют без перезапуска, очередь событий не теряется. Окно загрузки читает настройки, когда открылось главное окно Pilot: к этому времени общие настройки уже пришли. - Модули видят Pilot.ClientSdk. Модули Pilot грузятся в один AppDomain клиента. Сборка
113Pilot.ClientSdk.ext2загружена один раз, её типы доступны всем модулям. Поэтому в zip модулей её класть нельзя: вторая копия той же сборки даст конфликт типов. - Без сторонних зависимостей в коде. JSON, лог и ожидание подписок написаны вручную. Модуль не тянет NLog, Newtonsoft.Json и System.Reactive. Сторонние библиотеки в проекте только для эксперимента 2.1.0: в zip лежит
Humanizer.dll2.14.1 - общая библиотека для других модулей (они ссылаются на неё только для компиляции).DocumentFormat.OpenXmlиSharpVectorsподключены в.csproj, но в коде и в zip не используются. В NuGet-пакет эти зависимости не попадают (PrivateAssets=all): в нём одна зависимость,Ascon.Pilot.SDK. - Подписки SDK.
SdkSubscriptionпревращаетIObservableSDK вTask. Подписка создаётся и снимается на UI-потоке. При таймауте возвращается уже полученное, а не исключение. Отмена черезCancellationTokenснимает подписку.
7. Типовые проблемы
| Симптом | Причина | Решение |
|---|---|---|
Модуль не загружается: Could not load type 'Pilot.ClientSdk…' |
у пользователя не назначен Pilot.ClientSdk | назначить 113Pilot.ClientSdk.ext2 всем пользователям |
Сервис IObjectsRepository недоступен: модуль Pilot.ClientSdk не загружен… |
модуль вызывает Pilot раньше старта Pilot.ClientSdk |
вызвать PilotApi.Init(...) в конструкторе своего модуля |
| В Grafana нет данных | неверный statsUrl, сервис недоступен с рабочего места |
Pilot.ClientSdk.log («Статистика … не отправлена»); http://<хост>:5310/health с рабочего места |
| Сервис отвечает 401 | не совпадает apiKey |
API-ключ в общих настройках «Модули» (или в Pilot.ClientSdk.config.json) = COLLECTOR_API_KEY |
| В Grafana модуль называется именем сборки | в сборке нет AssemblyProduct |
задать [assembly: AssemblyProduct("NN.NNN - Название - (Код) - (CICD)")] |
| В окне загрузки «не скачан» | клиент не скачал zip модуля (обрыв связи при старте, нет места на диске, антивирус) | перезапустить Pilot; если не помогло - закрыть клиент и удалить папку Databases\<база>\<версия>\Plugins |
| В окне загрузки «не загружен» | zip скачан, но клиент не загрузил сборку (нет *.ext2.dll, конфликт зависимостей, модуль собран под более новый Pilot.ClientSdk) |
лог клиента Pilot; выложить Pilot.ClientSdk нужной версии |
| «загружен, без IModule» | стартовый класс не реализует IModule |
реализовать по разделу 2а |
| «нет отчёта о запуске» | IModule есть, но StartupRunner.Run(this) не вызван, или клиент не создал стартовый класс (ошибка MEF-импорта) |
добавить вызов в конструктор; смотреть лог клиента Pilot |
| Окно загрузки мешает (стенд, автотесты) | - | общие настройки «Модули»: окно «Только если модуль не загрузился» или «Не показывать» |
| Сторонний модуль всегда «не загружен» | модуль назначен, но клиент его не грузит (другой клиент, старая версия) | общие настройки «Модули» / «Не проверять модули» |
| Настройки из Pilot не действуют | в разделе битый JSON или клиент не получил общие настройки | Pilot.ClientSdk.log: «Настройки Pilot.ClientSdk: …»; трей / «Модули версии», строка «Настройки» |
| Нет модуля в «Версии на рабочих местах» | нет AssemblyCompany("CICD") или сборка не *.ext2 |
задать атрибут компании |