Миграция с классической интеграции .NET 6

Переместить существующее приложение Doconut.NET6 на текущий DI и асинхронный API

Doconut имеет две отдельные интеграции .NET 6. Они могут использовать одно и то же Doconut.NET6 имя пакета, поэтому определите поколение по API в приложении перед изменением пакетов, стартапа, лицензий или ресурсов браузера.

Какую интеграцию .NET 6 вы используете?

Если проект содержит…Поколение
app.MapWhen(... "DocImage.axd" ...)Устаревшее / классическое
new Viewer(_cache, _accessor, ...)Устаревшее / классическое
Viewer.DoconutLicense(...) или Viewer.SetLicensePlugin(...)Устаревшее / классическое
Вручную скопированный docViewer.js, documentLinks.js, или docViewer.UI.jsУстаревшее / классическое
builder.Services.AddDoconut(...)Текущая интеграция
app.UseDoconutResources() плюс app.UseDoconut()Текущая интеграция
Viewer поставляется через внедрение зависимостейТекущая интеграция
await viewer.OpenDocumentAsync(...)Текущая интеграция

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

Почему имя пакета NuGet может вас вводить в заблуждение

Обе генерации распространяются под идентификатором пакета Doconut.NET6. Ссылка на пакет, lock‑файл, или кэшированный .nupkg поэтому не определяют используемое API сами по себе. Зафиксируйте точную версию пакета и проверьте Program.cs, создание просмотрщика, открытие документов и скрипты браузера вместе.

Текущий релиз, проверенный для данного руководства, — Doconut.NET6 26.7.0. Его необязательные публичные пакеты — Doconut.NET6.Converter и Doconut.NET6.Dicom, зафиксированные на той же версии релиза, что и основной пакет.

Перед миграцией

  1. Создайте ветку и развертываемую резервную копию существующего приложения.
  2. Зафиксируйте точные версии основных и плагин‑пакетов.
  3. Составьте инвентарь всех сопоставлений DocImage.axd, вызовов new Viewer(...), вызовов загрузки лицензий, скопированных скриптов Doconut, пользовательских действий панели инструментов и конечных точек открытия документов.
  4. Сохраните текущие файлы .lic и секреты развертывания вне системы контроля версий.
  5. Соберите репрезентативный набор PDF, Office, изображений, CAD, email, DICOM, документов с возможностью поиска, защищённых паролем и аннотированных.
  6. Зафиксируйте текущий тайм‑аут сессии, поведение безопасности, шрифты и настройки платформы.

Перенесите одну среду перед изменением продакшена. Текущая интеграция меняет время жизни сервисов, маршрутизацию запросов, владение сессией и доставку клиентских ресурсов.

Совместимость пакетов и лицензий

Заменяйте или обновляйте основной пакет осознанно; не полагайтесь на идентичный идентификатор пакета для выбора нового API. Команда по умолчанию устанавливает последнюю стабильную версию:

bash
dotnet add package Doconut.NET6

Для воспроизводимой миграции к версии, проверенной в этом руководстве, укажите версию как отдельный параметр:

bash
dotnet add package Doconut.NET6 --version 26.9.0

Сохраняйте каждый плагин Doconut на той же версии, что и основной пакет. Текущая интеграция загружает лицензии один раз во время AddDoconut(), используя такой порядок приоритета:

text
LicenseStream > LicenseContent > LicensePath > automatic discovery

Автоматическое обнаружение ищет Doconut.Viewer.lic и сопутствующие файлы Doconut.Viewer.<Capability>.lic. Классический вызов Viewer.DoconutLicense(...) или Viewer.SetLicensePlugin(...) не является текущим механизмом стартапа. Переместите лицензию в DoconutOptions, держите сопутствующие файлы вместе при использовании автоматического обнаружения, перезапустите после изменения лицензии и проверьте возможности через IDoconutLicenseService.

Не полагайтесь на то, что наличие старой лицензии плагина подтверждает право на текущую сборку плагина. Тестируйте просмотрщик, Поиск, Аннотацию, Конвертер и DICOM отдельно, используя утверждённые артефакты релиза.

Запуск и внедрение зависимостей

Классические приложения создают Viewer с кэшем ASP.NET и зависимостями request‑accessor:

csharp
// Классическая интеграция — только контраст; не компилируйте это с текущим SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

Текущая интеграция регистрирует Doconut один раз и получает Viewer через внедрение зависимостей:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer является временным сервисом. Менеджер сеанса документа и его кэш владеют более длительным состоянием документа, а не конкретным внедрённым экземпляром Viewer.

Промежуточное ПО и маршрутизация ресурсов

Удалите классическую ветку MapWhen, которая обнаруживает DocImage.axd:

csharp
// Классическая интеграция — удалить во время переключения.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

В текущем конвейере:

  1. вызвать UseSession() до Doconut, пока включена безопасность сеанса;
  2. вызвать UseDoconutResources() перед UseDoconut();
  3. сохранять ResourcesPath, сгенерированные URL‑ресурсы и клиент ResPath согласованными;
  4. при сопоставлении UseDoconut() с веткой сохранять эту ветку и клиент BasePath согласованными.

MiddlewarePath — проверенная конфигурация; она не создаёт ветку ASP.NET Core сама по себе. Используйте либо простой конвейер в приведённом выше примере компиляции, либо явную схему app.Map("/doconut", branch => branch.UseDoconut()), используемую последовательно клиентом.

Конструирование и жизненный цикл Viewer

Удалите кэши объектов Viewer, принадлежащие приложению. Внедрите Viewer в конечную точку, Razor‑страницу, контроллер или областную сервис‑службу приложения:

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Возвращённый токен идентифицирует серверный сеанс документа. Обрабатывайте его как токен‑носитель учётных данных: не регистрируйте его, не сохраняйте и не помещайте в аналитику.

Открытие и закрытие документов

Замените синхронный OpenDocument(...) на OpenDocumentAsync(...):

csharp
// Текущая интеграция .NET 6: Viewer берётся из DI, а открытие документа происходит асинхронно.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Текущие перегрузки принимают путь к файлу или поток, необязательную конфигурацию формата, необязательный DocOptions и токен отмены. Закрывайте серверный сеанс явно, когда браузер больше не нуждается в нём:

csharp
viewer.CloseDocument(token);

Не переиспользуйте классический токен после перехода. Откройте каждый документ заново через текущий API.

Классы конфигурации

Текущий API разделяет задачи:

ЗадачаТекущий тип
Пути middleware, лицензирование, регистрация плагиновDoconutOptions
Пароль, таймаут, безопасность, водяной знакDocOptions
Рендеринг формата и DPIPdfConfig, WordConfig, ExcelConfig, и другие типы BaseConfig
Настройки виджетов браузераViewerConfig или эквивалентные параметры JavaScript
Сгенерированные CSS и скриптыCssConfig и ScriptConfig

Не переносите DocOptions.ImageResolution в качестве элемента управления рендерингом. Он устарел; установите BaseConfig.ImageResolution в конфигурацию, специфичную для формата. Проверьте все значения по умолчанию, а не полагайтесь на то, что классическая конфигурация ведёт себя одинаково.

Панель инструментов Viewer, поиск и аннотации

Не переносите старые скрипты по одному. Текущие справочные приложения собирают один полный пакет страницы:

  1. выпустить CSS Viewer и лицензированный CSS Search/Annotation с помощью ReferenceCss;
  2. отрисовать панель инструментов Viewer, принадлежащую приложению;
  3. отрисовать searchBarMount, annBarMount и требуемый монтировщик Viewer;
  4. выпустить скрипты Viewer и лицензированных модулей с помощью ReferenceScripts;
  5. загрузить собственный viewerToolbar.js приложения;
  6. инициализировать один objViewer;
  7. инициализировать лицензированные ленты Search и Annotation;
  8. вызвать attach(objViewer) для каждой ленты;
  9. открыть документ и вызвать objViewer.View(token).

Поиск и аннотации — это модули, присоединённые к тому же Viewer, а не независимые панели инструментов. Основная панель принадлежит хост‑приложению; ленты поиска и аннотаций встроены, их доступность управляется возможностями.

Удалите вручную скопированные классические файлы, такие как documentLinks.js и docViewer.UI.js, только после того, как текущая страница будет работать с ресурсами, генерируемыми ReferenceCss и ReferenceScripts.

Регистрация плагина

Классические статические методы лицензирования плагинов не регистрируют текущие плагины. Установите и явно зарегистрируйте каждый выпущенный пакет:

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() проверяет зарегистрированные возможности плагина при запуске. Converter и DICOM являются выпущенными плагинами .NET 6. Normal Search и Annotation — встроенные лицензированные функции, а не пакеты AddPlugin<TPlugin>().

Безопасность сеанса и документа

Текущая интеграция привязывает документы к непрозрачным токенам и кэшированным сеансам. При использовании значения по умолчанию UnsafeMode = false, UseDoconut() добавляет безопасность доступа к документу, и хост должен настроить сеанс ASP.NET:

csharp
builder.Services.AddDistributedMemoryCache(); // состояние сессии требует кеша (MVC/Razor Pages уже добавляют его)
builder.Services.AddSession();
app.UseSession();

Сохраняйте DocOptions.IsSecured = true, если только проверенный дизайн не требует иначе. Никогда не используйте UnsafeMode = true в качестве короткого пути миграции. Тестируйте запросы без токена, с некорректным токеном, с истёкшим токеном и с токеном из другого сеанса браузера.

Приложение‑образец Distributed добавляет билеты доступа и детали транспортировки. Эти API не требуются для обычной миграции в однопоточном режиме.

Тестирование миграции

Минимум, проверьте:

  • запуск приложения с производственной лицензией и всеми зарегистрированными плагинами;
  • CSS/скрипты Viewer и все запросы изображений страниц по выбранным путям;
  • открытие документа, навигацию, масштабирование, миниатюры, печать и явное закрытие;
  • поиск в документе с текстом и отсутствие возможности поиска в файле, содержащем только изображения;
  • загрузку, сохранение, экспорт аннотаций и управление возможностями;
  • обнаружение целей Converter, вывод, загрузку и состояние водяного знака;
  • страницы DICOM, кадры и анимацию; технические метаданные .NET 6 недоступны;
  • документы, защищённые паролем, пользовательские шрифты, нелатинский текст и настроенные тайм‑ауты;
  • отклонение токенов между сеансами и поведение при истёкшем сеансе;
  • мобильные устройства, тёмный режим и путь обратного прокси в продакшене.

План отката

Сохраняйте артефакт классического развертывания, соответствующие пакеты, файлы лицензий и скопированные ресурсы браузера вместе. Безопасный откат переключает всю генерацию приложения; он не смешивает классический сервер с текущими скриптами или текущий сервер с классическими вызовами DocImage.axd.

Перед переключением задокументируйте:

  • слот развертывания или артефакт, используемый для отката;
  • влияние на базу данных/кеш, если есть;
  • как будут аннулированы активные сеансы документов;
  • проверку состояния и тестовый документ, используемые для решения об откате;
  • кто может восстановить предыдущий набор пакетов и конфигурацию.

Унаследованная документация

Переведённое классическое руководство доступно по адресу Унаследованная настройка .NET 6. Новый Шлюз классической интеграции объясняет те же сигналы идентификации и ссылается обратно на это руководство по миграции.

Сохраняйте исторический URL в закладках и служебных билетах, пока классические установки ещё существуют. Он документирует другое поколение и не перенаправляется на текущий API.

Была ли эта страница полезной?