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

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

// 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, web document) у власний фіксований набір дозволених цілей. Не «жорстко» кодуйте цей enum у вашому UI: ?convert=open повертає реальний allowedTargets для завантаженого файлу, і саме його слід використовувати у випадаючому списку.

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

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

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; нічого не робить, якщо не в стані idle
conv.destroy();       // видаляє слухачі, очищає монтування; після цього екземпляр не придатний до використання

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

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

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

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

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

Власність ресурсів

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

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

Устранення неполадок

Водяний знак

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

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