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

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

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

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

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

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

Текущий релиз, проверенный для данного руководства, — 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. Зафиксируйте текущие тайм‑ауты сессий, поведение безопасности, шрифты и настройки платформы.

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

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

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

dotnet add package Doconut.NET6

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

dotnet add package Doconut.NET6 --version 26.7.0

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

LicenseStream > LicenseContent > LicensePath > automatic discovery

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

Не полагайтесь на то, что наличие старой лицензии плагина подтверждает право использования текущей сборки плагина. Тестируйте Viewer, Search, Annotation, Converter и DICOM отдельно, используя утверждённые артефакты релиза.

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

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

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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

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

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

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

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

// Classic integration — remove during the cutover.
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‑страницу, контроллер или сервис с областью действия:

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

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

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

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

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

viewer.CloseDocument(token);

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

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

Текущий API разделяет ответственности:

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

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

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

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

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

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

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

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

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

AddDoconut() проверяет возможности зарегистрированных плагинов при запуске. Converter и DICOM — это выпущенные плагины для .NET 6. Обычный поиск и аннотации являются встроенными лицензированными функциями, а не пакетами AddPlugin<TPlugin>().

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

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

builder.Services.AddSession();
app.UseSession();

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

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

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

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

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

План отката

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

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

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

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

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

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