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

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

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

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

dotnet add package Doconut.NET6.Converter

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

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

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

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

Методу AddConverter() не існує — модель плагінів Doconut уніфікована. Кожен плагін, включаючи Converter, реєструється однаково: викличте AddPlugin<TPlugin>() всередині AddDoconut(). ConverterPlugin постачається у власному пакеті NuGet, Doconut.NET6.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();         // повернутись до екрану бездіяльності/скидання; не викликає повторно onReady
conv.loadFile(file);  // запускає процес з об’єктом File; нічого не робить, якщо не перебуває у стані бездіяльності
conv.destroy();       // видаляє слухачі, очищає mount; екземпляр після цього не придатний до використання

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

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

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

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

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

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

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

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

Усунення неполадок

Водяний знак

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

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