Table of Contents

Миграция на клиентскую библиотеку Ascon.Polynom.Web.Api.Client

Статья описывает переход со старой библиотеки структур данных веб-сервера Ascon.Polynom.Web.Api.Data на клиентскую библиотеку Ascon.Polynom.Web.Api.Client, поставляемую NuGet-пакетом. Клиентская библиотека объединяет модели запросов и ответов, типизированные сервисы вызова методов API и встроенную инфраструктуру авторизации.

Кому адресовано

Потребителям web-API, которые:

  • ссылались на сборку Ascon.Polynom.Web.Api.Data через <Reference> или <ProjectReference>;
  • использовали модели и интерфейсы из пространств имён Ascon.Polynom.Web.Api.Data.*;
  • вызывали методы web-API вручную через HttpClient и сами подставляли заголовок Authorization: Bearer.

Что изменилось

Область Было (Ascon.Polynom.Web.Api.Data) Стало (Ascon.Polynom.Web.Api.Client)
Подключение <Reference> / <ProjectReference> на сборку продукта одна PackageReference на пакет Ascon.Polynom.Web.Api.Client
Пространство имён Ascon.Polynom.Web.Api.Data.* Ascon.Polynom.Web.Api.Client.*
Интерфейсы моделей Ascon.Polynom.Web.Api.Data.Interfaces.Models.*, .Interfaces.Requests.*, .Interfaces.Responses.* Ascon.Polynom.Web.Api.Client.Interfaces
Классы моделей Ascon.Polynom.Web.Api.Data.Models.*, .Requests.*, .Responses.* Ascon.Polynom.Web.Api.Client.Models
Перечисления Ascon.Polynom.Web.Api.Data.Interfaces.Enums Ascon.Polynom.Web.Api.Client.Enums
Вызов методов API ручной HttpClient и строки маршрутов типизированные сервисы Ascon.Polynom.Web.Api.Client.Services.*ApiClient
Авторизация ручная подстановка Authorization: Bearer AuthorizationService, AuthorizationMessageHandler, AddPolynomApiClient
JSON локальные настройки сериализации Ascon.Polynom.Web.Api.Client.Json.PolynomJsonOptions
Частично заданные значения Optional<T> Ascon.Polynom.Web.Api.Client.Optional<T>

Полное описание состава библиотеки, установки, настройки авторизации и списка сервисов приведено в разделе Клиентская библиотека .NET.

Краткое описание миграции

  1. Подключение библиотеки. Уберите ссылки на сборку Ascon.Polynom.Web.Api.Data и добавьте ссылку на NuGet-пакет клиентской библиотеки:

    <ItemGroup>
  <PackageReference Include="Ascon.Polynom.Web.Api.Client" Version="24.1.*" />
</ItemGroup>

  2. Пространства имён. В директивах using замените префикс Ascon.Polynom.Web.Api.Data на Ascon.Polynom.Web.Api.Client. Интерфейсы моделей теперь находятся в Ascon.Polynom.Web.Api.Client.Interfaces, классы — в Ascon.Polynom.Web.Api.Client.Models, перечисления — в Ascon.Polynom.Web.Api.Client.Enums.

  3. Вызовы методов API. Вместо ручных HTTP-запросов используйте типизированные сервисы *ApiClient из Ascon.Polynom.Web.Api.Client.Services. Сервисы возвращают Task<T?> и принимают CancellationToken:

    using Ascon.Polynom.Web.Api.Client.Models;
using Ascon.Polynom.Web.Api.Client.Services;

var page = await searchApiClient.ExecuteSearch(
    new SearchRequest { SearchText = "насос", PageNumber = 1, PageSize = 50 },
    cancellationToken);

  4. Авторизация. Управление сессией выполняет AuthorizationService. В приложениях с DI сервисы регистрируются расширением AddPolynomApiClient, в консольных сценариях без DI — фабрикой PolynomApiClientFactory. Обработчик AuthorizationMessageHandler сам подставляет заголовок Authorization: Bearer и при ответе 401 однократно обновляет токен:

    builder.Services.AddPolynomApiClient(options =>
{
    options.BaseAddress = new Uri("https://polynom-mdm.local:5100");
    options.AutoRefreshToken = true;
});

  5. Сериализация. Для ручной сериализации моделей используйте единые настройки PolynomJsonOptions.Options вместо собственных.

Критические изменения (Breaking Changes)

  1. Пространства имён Ascon.Polynom.Web.Api.Data.* заменены на Ascon.Polynom.Web.Api.Client.* — требуется правка директив using.
  2. Интерфейсы моделей объединены в одном пространстве имён Ascon.Polynom.Web.Api.Client.Interfaces (ранее — отдельные .Interfaces.Models, .Interfaces.Requests, .Interfaces.Responses).
  3. Классы моделей запросов и ответов перенесены в Ascon.Polynom.Web.Api.Client.Models (ранее — раздельные .Models, .Requests, .Responses).
  4. Подключение сборки продукта заменено на NuGet-пакет; прямые ссылки на DLL продукта не поддерживаются.
  5. Вызовы API и авторизация выполняются через сервисы библиотеки — ручной HttpClient, строки маршрутов и ручная подстановка заголовка авторизации не требуются.

Рекомендации по миграции

  1. Замените <Reference> / <ProjectReference> на <PackageReference Include="Ascon.Polynom.Web.Api.Client" />.
  2. Выполните глобальную замену Ascon.Polynom.Web.Api.Data → Ascon.Polynom.Web.Api.Client в директивах using и уточните пространства имён для моделей, интерфейсов и перечислений.
  3. Переведите обращения к web-API на типизированные сервисы *ApiClient; перенесите тела запросов в модели Ascon.Polynom.Web.Api.Client.Models.
  4. Настройте авторизацию через AddPolynomApiClient (DI) или PolynomApiClientFactory (без DI) и уберите ручную работу с токенами.
  5. Сверьте фактическое расположение конкретных типов по справочнику Клиентская библиотека .NET — имена и вложенность пространств имён могли измениться.
  6. Соберите приложение и проверьте авторизацию и вызовы методов по неинтерактивному сценарию.

Возможные ошибки

Симптом Причина Решение
Тип не найден после замены using тип остался в другом пространстве имён новой библиотеки проверьте Ascon.Polynom.Web.Api.Client.Interfaces, .Models или .Enums
Ошибка восстановления пакета не подключён NuGet-фид с пакетом подключите фид с Ascon.Polynom.Web.Api.Client (в SDK доступен локальный фид SDK/Web/Packages/dotnet)
401 при вызове метода не выполнена авторизация или не настроен обработчик вызовите AuthorizationService.SignInAsync(...) и используйте клиенты из AddPolynomApiClient/PolynomApiClientFactory
Токен не подставляется в запрос HttpClient создан в обход библиотеки получайте клиенты из DI или фабрики, а не создавайте HttpClient вручную
Значение поля теряется при обновлении используется null вместо незаданного значения применяйте Ascon.Polynom.Web.Api.Client.Optional<T>

См. также