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

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

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

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

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

Обе версии поставляются под идентификатором пакета Doconut.NET6. Ссылка на пакет, файл блокировки или кэшированный .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. Зафиксируйте текущие таймауты сессий, поведение безопасности, шрифты и настройки платформы.

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

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

Заменяйте или обновляйте основной пакет осознанно; не полагайтесь на идентичный идентификатор пакета для выбора нового 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 и request‑accessor:

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

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

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.

Middleware и маршрутизация ресурсов

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

// Классическая интеграция — удалить во время перехода.
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(...):

// Текущая интеграция .NET 6: Viewer получен через DI, а открытие документа асинхронно.
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. Normal Search и Annotation — встроенные лицензированные функции, а не пакеты AddPlugin<TPlugin>().

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

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

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.

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

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

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

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

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