Міграція

Оновлення до Doconut на .NET 8

Дві міграції розглядаються на цій сторінці: оновлення версії пакету у .NET 8 та перенесення інтеграції зі старішого фреймворку Doconut (.NET 6, .NET Standard 2.0, .NET Framework 4.7) на API .NET 8.

Оновлення версії пакету

  1. Оновіть пакет (і будь‑які пакети‑плагіни — тримайте їхні версії синхронізованими):
bash
dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom
  1. Перевірте вікно ліцензії. Ліцензія охоплює діапазон версій. Якщо нова версія виходить за його межі, відкриття блокується — OpenDocumentAsync викидає LicenseException (fail‑fast); вона не повертається до водяного знака, і IsVersionValid повертає false. Оновіть, замініть файл .lic і перезапустіть застосунок, щоб AddDoconut() завантажив нову ліцензію.
  2. Перебудуйте та дозвольте NuGet відновити зазначені версії залежностей — не закріплюйте System.Text.Json або System.Drawing.Common (див. розділ Troubleshooting для точних помилок, які виникають при пониженні версії).
  3. Проведіть smoke‑тест одного документа кожного формату, який ви використовуєте.

Перенесення з .NET 6 / .NET Standard 2.0

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

Питання.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
MiddlewareРучне підключення обробників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 повертає токен (швидкий старт демонструє цей шаблон).
  • Статичні методи ліцензії → джерела ліцензій у DoconutOptions.
  • Синхронний OpenDocument → await OpenDocumentAsync.
  • Viewer.ReferenceScripts() / ReferenceCss() присутні в обох світах — у .NET 8 вони приймають об’єкти ScriptConfig/CssConfig і підлягають ліцензійному контролю.
  • Властивості контролу (ShowThumbs, PageZoom, FixedZoom, …) → ті ж назви у ViewerConfig / параметрах JS‑віджету docViewer.
  • Методи експорту, що повертають byte[] → асинхронні API експорту анотацій у Viewer.

Плануйте це як переписування шару хостингу навколо незмінної концепції: відкриття → токен → віджет.

Примітка щодо назви

У всіх фреймворках клас називається Viewer — якщо ви натрапляєте на DocumentViewer у старих фрагментах коду або сторонніх статтях, такого типу в SDK ніколи не існувало.

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

  1. Замініть пакети; вирівняйте версії пакетів‑плагінів.
  2. Перенесіть налаштування ліцензії у AddDoconut(); видаліть статичні виклики ліцензії.
  3. Перетворіть виклики відкриття на асинхронні; замініть Dispose/CloseDocument без параметрів на CloseDocument(token).
  4. Замініть використання viewer.Converter на реєстрацію плагіна Converter + DocumentConverter.
  5. Перепровірте шлях безпеки: AddSession()/UseSession() тепер обов’язкові за замовчуванням.

Чи була ця сторінка корисною?