Плагін Конвертера

Плагін Converter перетворює Doconut у сервіс конвертації документів. Він забезпечує движок, що стоїть за публічним фасадом DocumentConverter, і — за бажанням — готовий віджет зі своїм HTTP‑контрактом, тож ви можете конвертувати документи з C#, з віджета або з власного фронтенду, який ви напишете самі.

Встановити пакет

Встановіть останню стабільну версію плагіна Converter:

dotnet add package Doconut.NET8.Converter

Щоб зафіксувати плагін на поточному випуску 26.7.0, передайте версію окремо:

dotnet add package Doconut.NET8.Converter --version 26.7.0

Тримайте пакет Converter на тій же версії, що і Doconut.NET8. Ідентифікатор пакету
Doconut.NET8.Converter; .26.7.0 з'являється лише у назві завантаженого файлу .nupkg.

Зареєструвати плагін

Методу AddConverter() не існує — модель плагінів Doconut уніфікована. Кожен плагін, включаючи Converter, реєструється однаково: викличте AddPlugin<TPlugin>() всередині AddDoconut(). ConverterPlugin постачається у власному пакеті NuGet, Doconut.NET8.Converter, встановленому разом із базовим пакетом переглядача.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Цей виклик генерує виключення під час запуску через відсутню ліцензію, застарілий файл TRIAL або нестандартну ліцензію, яка не надає можливість Converter — InvalidOperationException, підняте всередині AddDoconut(), перед тим як застосунок обробляє запити. Приймаються тимчасові реєстрації Demo/NFR; після закінчення їх терміну дії конвертація залишається доступною з водяним знаком у вихідному файлі. Безкоштовного безлімітного рівня немає. Дивіться Налаштування ліцензії для інформації про завантаження ліцензій.

Конвертувати з C#

Кожна конвертація повертає придатний до пошуку MemoryStream, розташований на позиції 0, готовий до читання або копіювання одразу. Отримайте DocumentConverter з DI там, де це потрібно — він безстановий за задумом, тому одну інстанцію безпечно використовувати повторно в різних запитах.

// Впровадьте DocumentConverter; його конструктор є internal, тому ніколи не `new` його.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension включає початкову крапку. password є null, якщо документ не захищений.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Дві деталі, які легко переплутати: sourceExtension у перевантаженні потоку має включати початкову крапку (".xlsx", а не "xlsx") — конвертер порівнює її з каталогом форматів, і чисте розширення не буде розпізнано. І, незважаючи на назву, WordToHtmlAsync повертає Task<Stream>, а не Task<string> — ви отримуєте HTML‑документ (зображення вбудовані у Base64) як потік, так само, як і будь‑який інший результат конвертації.

Цільові формати

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Не кожне джерело конвертується у кожну ціль — плагін відображає сімейство форматів джерела (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, веб‑документ) у власний фіксований набір дозволених цілей. Не жорстко кодуйте цей enum у списку цілей вашого інтерфейсу: ?convert=open повертає фактичний allowedTargets для будь‑якого лише що завантаженого файлу, і саме це має керувати вибором.

Вбудований віджет

Віджет ?convert=open|run|download кінцеві точки є за запитом та вимкнені за замовчуванням — захищено за замовчуванням. Увімкніть їх на сервері разом із реєстрацією плагіна:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Без AddConverterWidget() три кінцеві точки ?convert= відповідають 404 — проте сам файл JS все одно подається (це простий вбудований статичний ресурс; лише кінцеві точки, до яких він звертається, захищені). AddConverterWidget() все ще вимагає реєстрації плагіна Converter та ліцензії, що надає Converter — вона не надає прав на конвертацію самостійно.

Налаштування віджета

Параметри ініціалізації, передані до Doconut.convert(selector, options):

Зворотні виклики:

Doconut.convert() повертає сам екземпляр віджета — збережіть його, щоб керувати віджетом програмно:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // повернутись до екрану idle/drop; не викликає повторно onReady
conv.loadFile(file);  // запускає процес з об’єктом File; no-op, якщо не currently idle
conv.destroy();       // видаляє слухачі, очищає mount; instance непрацездатна після цього

Створіть власний інтерфейс

Віджет — це лише клієнт для цього HTTP‑контракту — створіть власний інтерфейс безпосередньо проти нього для іншого UX. Усі три маршрути розташовані під гілкою ASP.NET, де змонтовано UseDoconut() (зазвичай /doconut):

Завантажені байти джерела зберігаються на сервері з TTL 30 хвилин; коли цей проміжок закінчується, run відповідає 404 і файл треба знову відкрити. Конвертований результат зберігається в тому ж сховищі — downloadToken отримує власне нове 30‑хвилинне вікно після завершення конвертації — тоді як resultToken є звичайним токеном сесії переглядача, тривалість якого слідує кешу сесії переглядача, незалежно від сховища.

sourceExt у відповіді open не має початкової крапки (наприклад, "docx") — протилежна конвенція до параметра sourceExtension у DocumentConverter.ConvertAsync, який вимагає її.

Режими відмов, згруповані за маршрутом:

Володіння ресурсом

Конвертер повертає seekable MemoryStream, розташований у нулі. Викликаючий володіє цим потоком і повинен його звільнити після копіювання або повернення його вмісту. Сервіс DocumentConverter сам по собі безстанний і отримується через впровадження залежностей; не створюйте і не звільняйте сервіс вручну.

Для веб‑віджету, сховища завантаження та скачування мають незалежні TTL у 30 хвилин. resultToken переглядача слідує життєвому циклу сесії переглядача. Закриття результату переглядача не видаляє ще дійсне сховище завантаження, і скидання віджету браузера не продовжує жоден з TTL.

Усунення проблем

Водяний знак

Після реєстрації ConverterPlugin ліцензія хоста перебуває в одному з трьох станів:

Обидва шляхи виклику обчислюють прапорець за тим же правилом: фасад DocumentConverter C# отримує його внутрішньо з стану IsViewerLicensed та IsTemporary ліцензії, а обробник ?convert=run віджету виконує еквівалентну перевірку (IsViewerLicensed && !IsTrial && !IsTemporary), щоб заповнити поле watermarked, яке він повертає. Інтеграцію можна створити та протестувати повністю на оцінювальній ліцензії перед покупкою — змінюються лише байти вихідних даних.