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

Плагін 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 там, де це потрібно — він безстановий за задумом, тому одну інстанцію безпечно використовувати повторно в різних запитах.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
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, веб‑документ) зі своїм фіксованим набором дозволених цілей. Не жорстко кодуйте цей перелік у вашому інтерфейсі: ?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();         // back to the idle/drop screen; does not re-fire onReady
conv.loadFile(file);  // starts the flow with a File object; no-op unless currently idle
conv.destroy();       // removes listeners, empties the mount; the instance is unusable after this

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

Віджет — лише клієнт для цього 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, яке повертає. Інтеграцію можна створити та протестувати повністю на оцінювальній ліцензії перед покупкою — змінюються лише байти вихідного файлу.