Два типи міграції розглядаються на цій сторінці: оновлення версії пакету у .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 (дивіться розділ Устранення проблем для точних помилок, які викликає пониження версії).
Швидко протестуйте один документ для кожної сімейства форматів, які ви використовуєте.

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

API .NET 8 — це перепроектування навколо DI та async. Відповідність:

Питання	.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 замінює модель контролю на проміжне ПЗ + 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() обов’язкові з типовою безпекою (плюс AddDistributedMemoryCache() у мінімальному API‑застосунку).