Два типа миграций представлены на этой странице: обновление версии пакета в .NET 8 и перенос интеграции со старой платформы Doconut (.NET 6, .NET Standard 2.0, .NET Framework 4.7) на API .NET 8.

Обновление версии пакета

Обновите пакет (и любые пакеты плагинов — поддерживайте версии согласованными):

bash

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom

Проверьте окно лицензии. Лицензия охватывает диапазон версий. Если новая версия выходит за его пределы, открытие блокируется — OpenDocumentAsync бросает LicenseException (быстрый отказ); он не переходит к водяному знаку, и IsVersionValid возвращает false. Обновите, замените файл .lic и перезапустите приложение, чтобы AddDoconut() загрузил новую лицензию.
Пересоберите проект и позвольте NuGet восстановить объявленные версии зависимостей — не фиксируйте заново System.Text.Json или System.Drawing.Common (см. раздел «Устранение неполадок» для точных ошибок, вызываемых откатом версии).
Проведите быстрый тест (smoke‑test) одного документа для каждой семейства форматов, которые вы используете.

Миграция с .NET 6 / .NET Standard 2.0

API .NET 8 — это переработка вокруг DI и асинхронности. Соответствие:

Задача	.NET 6 / Standard 2.0	.NET 8
Настройка	Создать `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + внедрить `Viewer`
Лицензия	Статический `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` для каждого плагина	`options.LicensePath` / `LicenseContent` / `LicenseStream` — одна лицензия, автоматическое обнаружение файлов плагинов
Открытие	`viewer.OpenDocument(...)` (синхронно)	`await viewer.OpenDocumentAsync(...)`
Закрытие	`viewer.CloseDocument()` или `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` не является `IDisposable`
Жизненный цикл	`Viewer` реализует `IDisposable`, хранит открытый документ	`Viewer` без состояния; сессии хранятся в кэше по токенам
Конвертер	свойство `viewer.Converter`	Плагин Converter (`AddPlugin<ConverterPlugin>()`) + сервис `DocumentConverter`
Классы конфигурации	пространства имён `Doconut.Configs.View.*`	Все в пространстве имён `Doconut`
Промежуточное ПО	Ручное подключение обработчиков	`app.UseDoconutResources()` + `app.UseDoconut()`

Типичный пример до/после:

text

// .NET 6 (old API, shown for contrast — not valid on .NET 8)
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.Viewer.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());

csharp

// .NET 8 — Viewer injected, license configured once in AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Миграция с .NET Framework 4.7 (Web Forms)

Viewer версии 4.7 является WebControl; .NET 8 заменяет модель управления на промежуточное ПО + DI‑службу:

Элемент <doconut:DocViewer runat=server> исчезает — страница размещает пару div‑виджетов, а ваш конечный пункт возвращает токен (в Quick Start показан шаблон).
Статические методы лицензии → источники лицензий DoconutOptions.
Синхронный OpenDocument → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss() существуют в обеих версиях — версии .NET 8 принимают объекты ScriptConfig/CssConfig и работают только при наличии лицензии.
Свойства контроля (ShowThumbs, PageZoom, FixedZoom, …) → те же имена в ViewerConfig / параметрах JS docViewer.
Методы экспорта, возвращающие byte[], → асинхронные API экспорта аннотаций в Viewer.

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

Примечание к именованию

Во всех фреймворках класс называется Viewer — если вы встречаете DocumentViewer в старых фрагментах кода или сторонних статьях, такого типа никогда не было в SDK.

Чек‑лист миграции

Замените пакеты; согласуйте версии пакетов плагинов.
Перенесите настройку лицензии в AddDoconut(); удалите вызовы статических методов лицензии.
Сделайте вызовы открытия асинхронными; замените Dispose/CloseDocument без параметров на CloseDocument(token).
Замените использование viewer.Converter на регистрацию плагина Converter + DocumentConverter.
Повторно протестируйте путь безопасности: теперь AddSession()/UseSession() обязательны при настройках безопасности по умолчанию.