Два типа миграций представлены на этой странице: обновление версии пакета в .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‑тест одного документа для каждой используемой семейства форматов.

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

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

Задача	.NET 6 / Standard 2.0	.NET 8
Настройка	Construct `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
Лицензия	Static `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — one license, auto-discovery for plugin files
Открытие	`viewer.OpenDocument(...)` (synchronous)	`await viewer.OpenDocumentAsync(...)`
Закрытие	`viewer.CloseDocument()` or `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` is not `IDisposable`
Время жизни	`Viewer` implements `IDisposable`, holds the open document	`Viewer` is stateless; sessions live in the cache under tokens
Конвертер	`viewer.Converter` property	The Converter plugin (`AddPlugin<ConverterPlugin>()`) + the `DocumentConverter` service
Классы конфигурации	`Doconut.Configs.View.*` namespaces	All in the `Doconut` namespace
Промежуточное ПО	Manual handler wiring	`app.UseDoconutResources()` + `app.UseDoconut()`

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

text

// .NET 6 (старый API, показан для сравнения — недоступен в .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 внедряется, лицензия настраивается один раз в AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

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

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

Элемент <doconut:DocViewer runat=server> исчезает — страница размещает пару div‑виджетов, а ваш endpoint возвращает токен (см. 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() с настройками безопасности по умолчанию (плюс AddDistributedMemoryCache() в приложении minimal-API).