На цій сторінці розглядаються два типи міграції: оновлення версії пакету у .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 => …)` + inject `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‑віджетів, а ваш кінцевий пункт повертає токен (швидкий старт показує шаблон).
Статичні методи ліцензії → джерела ліцензії 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() тепер обов’язкові за замовчуванням.