Миграция с классической интеграции .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, зафиксированные на той же версии релиза, что и основной пакет.
Перед миграцией
- Создайте ветку и развертываемую резервную копию существующего приложения.
- Зафиксируйте точные версии основных и плагин‑пакетов.
- Составьте инвентарь всех сопоставлений
DocImage.axd, вызововnew Viewer(...), вызовов загрузки лицензий, скопированных скриптов Doconut, пользовательских действий панели инструментов и конечных точек открытия документов. - Сохраните текущие файлы
.licи секреты развертывания вне системы контроля версий. - Соберите репрезентативный набор PDF, Office, изображений, CAD, email, DICOM, документов с возможностью поиска, защищённых паролем и аннотированных.
- Зафиксируйте текущий тайм‑аут сессии, поведение безопасности, шрифты и настройки платформы.
Перенесите одну среду перед изменением продакшена. Текущая интеграция меняет время жизни сервисов, маршрутизацию запросов, владение сессией и доставку клиентских ресурсов.
Совместимость пакетов и лицензий
Заменяйте или обновляйте основной пакет осознанно; не полагайтесь на идентичный идентификатор пакета для выбора нового API. Команда по умолчанию устанавливает последнюю стабильную версию:
dotnet add package Doconut.NET6Для воспроизводимой миграции к версии, проверенной в этом руководстве, укажите версию как отдельный параметр:
dotnet add package Doconut.NET6 --version 26.9.0Сохраняйте каждый плагин Doconut на той же версии, что и основной пакет. Текущая интеграция загружает лицензии один раз во время AddDoconut(), используя такой порядок приоритета:
LicenseStream > LicenseContent > LicensePath > automatic discoveryАвтоматическое обнаружение ищет Doconut.Viewer.lic и сопутствующие файлы Doconut.Viewer.<Capability>.lic. Классический вызов Viewer.DoconutLicense(...) или Viewer.SetLicensePlugin(...) не является текущим механизмом стартапа. Переместите лицензию в DoconutOptions, держите сопутствующие файлы вместе при использовании автоматического обнаружения, перезапустите после изменения лицензии и проверьте возможности через IDoconutLicenseService.
Не полагайтесь на то, что наличие старой лицензии плагина подтверждает право на текущую сборку плагина. Тестируйте просмотрщик, Поиск, Аннотацию, Конвертер и 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.
Промежуточное ПО и маршрутизация ресурсов
Удалите классическую ветку MapWhen, которая обнаруживает DocImage.axd:
// Классическая интеграция — удалить во время переключения.
app.MapWhen(
context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
branch => branch.UseDoconut(new DoconutOptions()));В текущем конвейере:
- вызвать
UseSession()до Doconut, пока включена безопасность сеанса; - вызвать
UseDoconutResources()передUseDoconut(); - сохранять
ResourcesPath, сгенерированные URL‑ресурсы и клиентResPathсогласованными; - при сопоставлении
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 разделяет задачи:
| Задача | Текущий тип |
|---|---|
| Пути middleware, лицензирование, регистрация плагинов | DoconutOptions |
| Пароль, таймаут, безопасность, водяной знак | DocOptions |
| Рендеринг формата и DPI | PdfConfig, WordConfig, ExcelConfig, и другие типы BaseConfig |
| Настройки виджетов браузера | ViewerConfig или эквивалентные параметры JavaScript |
| Сгенерированные CSS и скрипты | CssConfig и ScriptConfig |
Не переносите DocOptions.ImageResolution в качестве элемента управления рендерингом. Он устарел; установите BaseConfig.ImageResolution в конфигурацию, специфичную для формата. Проверьте все значения по умолчанию, а не полагайтесь на то, что классическая конфигурация ведёт себя одинаково.
Панель инструментов Viewer, поиск и аннотации
Не переносите старые скрипты по одному. Текущие справочные приложения собирают один полный пакет страницы:
- выпустить CSS Viewer и лицензированный CSS Search/Annotation с помощью
ReferenceCss; - отрисовать панель инструментов Viewer, принадлежащую приложению;
- отрисовать
searchBarMount,annBarMountи требуемый монтировщик Viewer; - выпустить скрипты Viewer и лицензированных модулей с помощью
ReferenceScripts; - загрузить собственный
viewerToolbar.jsприложения; - инициализировать один
objViewer; - инициализировать лицензированные ленты Search и Annotation;
- вызвать
attach(objViewer)для каждой ленты; - открыть документ и вызвать
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.
Перед переключением задокументируйте:
- слот развертывания или артефакт, используемый для отката;
- влияние на базу данных/кеш, если есть;
- как будут аннулированы активные сеансы документов;
- проверку состояния и тестовый документ, используемые для решения об откате;
- кто может восстановить предыдущий набор пакетов и конфигурацию.
Унаследованная документация
Переведённое классическое руководство доступно по адресу Унаследованная настройка .NET 6. Новый Шлюз классической интеграции объясняет те же сигналы идентификации и ссылается обратно на это руководство по миграции.
Сохраняйте исторический URL в закладках и служебных билетах, пока классические установки ещё существуют. Он документирует другое поколение и не перенаправляется на текущий API.
Была ли эта страница полезной?